### Install Swagger CLI Tool

Source: https://github.com/beckn/protocol-specifications/blob/master/api/transaction/README.md

Provides the command to install the swagger command-line interface tool globally using npm, which is required for bundling OpenAPI definitions.

```bash
sudo npm install -g swagger-cli
```

--------------------------------

### Schema Index File Example

Source: https://github.com/beckn/protocol-specifications/blob/master/api/registry/README.md

An example of how to structure the `index.yaml` file within the `api/registry/components/schemas/` directory. This file lists all schema files with their respective `$ref` pointers, ensuring they are compiled correctly.

```yaml
Gps:
  $ref: "../../../../schema/Gps.yaml"

Location:
  $ref: "../../../../schema/Location.yaml"
...
```

--------------------------------

### Install Swagger CLI

Source: https://github.com/beckn/protocol-specifications/blob/master/api/registry/README.md

Command to install the swagger command-line tool globally using npm. This tool is required for bundling OpenAPI specifications.

```bash
sudo npm install -g swagger-cli
```

--------------------------------

### Unresolved OpenAPI Index File Example

Source: https://github.com/beckn/protocol-specifications/blob/master/api/registry/README.md

An example of the `index.yaml` file located in the `api/registry/components/` directory. This file contains the base OpenAPI structure and references to individual API definitions found in the `io` folder, serving as the input for the bundling process.

```APIDOC
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"
...
```

--------------------------------

### HTML Form Example for Package Details

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-007-The-XInput-Schema.md

An example of an HTML form used to collect specific details about a package, including item count, dimensions, and category, before order confirmation.

```html
<form action="https://api.example-bpp.com/sendPackageDetails" method="post">
  <label for="itemCount">Number of items</label>
  <input type="number" id="itemCount" name="itemCount" value="0" />
  <label for="plength">Package length in cm</label>
  <input type="number" id="plength" name="plength" value="0" />
  <label for="pwidth">Package width in cm</label>
  <input type="number" id="pwidth" name="pwidth" value="0" />
  <label for="pheight">Package height in cm</label>
  <input type="number" id="pheight" name="pheight" value="0" />
  <label for="itemCategory">Select your degree</label>
  <select name="itemCategory" id="itemCategory">
    <option value="fnb">Food and Beverages</option>
    <option value="bns">Books and Stationery</option>
    <option value="etg">Electronic Goods</option>
    <option value="hhg">Household goods</option>
  </select><br/><br/>
  <input type="hidden" id="nonce" name="nonce" value="t8923y4ryu328473y4" />
</form>
```

--------------------------------

### BLAKE2b-512 Hashing Example

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP-Draft-01.md

Demonstrates the output of the BLAKE2b-512 hashing algorithm for a sample input string, shown in both hexadecimal and base64 encoded formats.

```text
BLAKE2b-512("The quick brown fox jumps over the lazy dog") =
a8add4bdddfd93e4877d2746e62817b116364a1fa7bc148d95090bc7333b3673f82401cf7aa2e4cb1ecd90296e3f14cb5413f8ed77be73045b13914cdcd6a918

Base64 encoded:
qK3Uvd39k+SHfSdG5igXsRY2Sh+nvBSNlQkLxzM7NnP4JAHPeqLkyx7NkCluPxTLVBP47Xe+cwRbE5FM3NapGA==
```

--------------------------------

### Beckn Payment Object Examples

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md

Illustrates various configurations of the Beckn Payment Object for different payment scenarios, including collection by BAP or BPP, and different transaction stages and methods.

```JSON
{
    "collected_by": "bap",
    "uri": "payto://bank/98273982749428?amount=$currency:$value&ifsc=$ifsc&message=hello",
    "tl_method": "PAYTO",
    "type": "POST_FULFILLMENT",
    "status": "NOT-PAID",
    "params": {
        "ifsc": "SBIN0000575",
        "value": "200",
        "currency": "INR"
    },
    "time": {
        "range": {
            "end": "2021-11-30 00:00:00"
        }
    }
}
```

```JSON
{
    "uri": "payto://upi/example@upi?amount=$currency:$value&message=hello",
    "tl_method": "PAYTO",
    "type": "ON-ORDER",
    "status": "NOT-PAID",
    "params": {
        "value": "200",
        "currency": "INR"
    }
}
```

```JSON
{
    "uri": "https://pay.example.com?amount=$value&cur=$currency",
    "tl_method": "HTTP/POST",
    "type": "ON-ORDER",
    "status": "NOT-PAID",
    "params": {
        "value": "200",
        "currency": "INR"
    }
}
```

--------------------------------

### Example BAP Search Request Body

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP-Draft-01.md

This JSON object represents an example request body sent by a BAP to a BG (Beckn Gateway) for a search action. It includes context like domain, city, transaction ID, and message details specifying fulfillment locations.

```JSON
{
  "context": {
    "domain": "nic2004:60212",
    "country": "IND",
    "city": "Kochi",
    "action": "search",
    "core_version": "0.9.1",
    "bap_id": "bap.stayhalo.in",
    "bap_uri": "https://8f9f-49-207-209-131.ngrok.io/protocol/",
    "transaction_id": "e6d9f908-1d26-4ff3-a6d1-3af3d3721054",
    "message_id": "a2fe6d52-9fe4-4d1a-9d0b-dccb8b48522d",
    "timestamp": "2022-01-04T09:17:55.971Z",
    "ttl": "P1M"
  },
  "message": {
    "intent": {
      "fulfillment": {
        "start": {
          "location": {
            "gps": "10.108768, 76.347517"
          }
        },
        "end": {
          "location": {
            "gps": "10.102997, 76.353480"
          }
        }
      }
    }
  }
}
```

--------------------------------

### xForms 2.0 Submission URL Example

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-007-The-XInput-Schema.md

Demonstrates the syntax for defining a submission URL in xForms 2.0 using the 'action' attribute within the 'xforms:submission' tag. This specifies the endpoint for form data submission.

```XML
<xforms:submission action="http://example.com/submitForm" method="post" includenamespaceprefixes=""/>
```

--------------------------------

### Bundle OpenAPI Definitions with swagger-cli

Source: https://github.com/beckn/protocol-specifications/blob/master/api/transaction/README.md

Command to bundle a set of OpenAPI definitions into a single, resolved YAML file using the swagger-cli tool. It takes an input index file and specifies an output file path.

```bash
swagger-cli bundle api/transaction/components/index.yaml --outfile api/transaction/build/transaction.yaml --type yaml
```

--------------------------------

### Schema Index File Structure

Source: https://github.com/beckn/protocol-specifications/blob/master/api/transaction/README.md

Defines the structure for the schema index file (index.yaml) used to list and reference schema files within the core/v0/api/components/schemas/ directory. Ensures all schemas are compiled.

```yaml
Ack:
  $ref: "../../../../Ack.yaml"

AddOn:
  $ref: "../../../../AddOn.yaml"
...
```

--------------------------------

### BECKN Candidate Information HTML Form

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-007-The-XInput-Schema.md

An example HTML form used in a BECKN protocol scenario for a recruitment agency to collect candidate details before confirming a job application. This form includes fields for location preference, experience, and technologies.

```html
<form action="https://api.example-bpp.com/candidateDetails" name="job_application" method="post">
  <label for="locationPreference">Select you preferred location of work</label>
  <select name="backend_technologies" id="example-bpp.com/locationPreference">
    <option value="std:011">Delhi</option>
    <option value="std:080">Bangalore</option>
    <option value="remote">Remote</option>
  >
  <label for="experience">Years of experience</label>
  <input type="number" id="years_of_experience" name="experience" value="0" />
  <label for="backend_technologies">Select the technologies that you have experience in</label>
  <select name="backend_technologies" id="example-bpp.com/backend_technologies" multiple>
    <option value="php">PHP</option>
    <option value="ruby_on_rails">Ruby on Rails</option>
    <option value="node_js">Node JS</option>
    <option value="python">Python</option>
  >
  <label for="other_technologies">Select any other technologies that you are profient in</label>
  <input type="text" id="example-bpp.com/other_technologies" name="other_technologies" value="0" />
  <input type="hidden" id="nonce" name="nonce" value="t8923y4ryu328473y4" />
</form>
```

--------------------------------

### HTML Form Submission URL Example

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-007-The-XInput-Schema.md

Illustrates how the submission URL is specified within an HTML form tag using the 'action' attribute. This is crucial for BAPs to know where to send form data.

```HTML
<form action="http://example.com/submitForm" method="post"> ... </form>
```

--------------------------------

### Unresolved OpenAPI Definition Structure

Source: https://github.com/beckn/protocol-specifications/blob/master/api/transaction/README.md

Illustrates the structure of an unresolved OpenAPI definition file (index.yaml) located in api/transaction/components/. It includes API metadata and path definitions referencing schema components.

```yaml
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"

...
```

--------------------------------

### Beckn Payment Collection Example (JSON)

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md

This JSON payload illustrates a payment collection scenario within the Beckn protocol. It details payment collection by a BAP, the UPI payment URI, currency, amount, and the settlement time range. This structure is used to represent payment-related information in Beckn transactions.

```json
{
    "collected_by": "bap",
    "uri": "upi://pay?pa=UPIID@oksbi&amp;pn=NAME&amp;&tr=123456789&amp;cu=INR&amp;am=200",
    "tl_method": "UPI",
    "type": "POST_FULFILLMENT",
    "status": "NOT-PAID",
    "params": {
        "value": "200",
        "currency": "INR"
    },
    "time": {
        "range": {
            "end": "2022-02-15 00:00:00"
        }
    }
}
```

--------------------------------

### BECKN Protocol Form Schemas

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-007-The-XInput-Schema.md

Defines the core schemas for handling custom user input via forms within the BECKN protocol. This includes XInput for integrating forms into transactions, Form for defining the form structure and content source, FormResponse for capturing submission results, and Error for detailing any issues during submission. Usage examples illustrate integration points within Item, Order, Feedback, and CancellationTerm schemas.

```APIDOC
BECKN Protocol Form Schemas:

XInput:
  type: object
  properties:
    form:
      $ref: Form
    required:
      description: Indicates whether the form data is mandatorily required by the BPP to confirm the order.
      type: boolean
      default: true

Form:
  description: Describes a form that needs to be rendered to the BAP user before the confirmation of an order.
  type: object
  properties:
    url:
      description: The URL from where the form can be fetched. The content fetched from the url must be processed as per the mime_type specified in this object. The BAP can choose to render the form as-is as an embeddable element, or process it further to blend it with the style of the application. In case the interface is non-visual, the BAP can process the form data and reproduce it as per the UI requirements.
      type: string
      format: uri
    mime_type:
      description: This field indicates the nature and format of the form received by querying the url. MIME types are defined and standardized in IETF's RFC 6838. If the mime_type is text/html, the application must render it inside a web view. If the mime_type is application/xml, then the application must consider it as an xForms 2.0 object and render it as per the XForms 2.0 specification.
      type: string
      enum:
      - text/html
      - application/xml
    submission_id:
      type: string
      format: uuid

FormResponse:
  description: Describes the response to a form submission
  type: object
  properties:
    status:
      description: Contains the status of form submission.
      type: boolean
      default: true
    submission_id:
      description: This contains a UUID generated by the BPP on successful submission of the form. 
      type: string
      format: uuid
    errors:
      type: array
      items:
        $ref: Error

Error:
  description: Describes an error object returned by the API in case of an exception scenario. The exception may be a technical one like a schema or a signature verification error; or business-related like an item not found, or an agent not available.
  type: object
  properties:
    code:
      type: string
      description: For full list of error codes, refer to docs/protocol-drafts/BECKN-RFC-005-ERROR-CODES-DRAFT-01.md of this repo
    path:
      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:
    - code
    - path

Usage Examples:

The XInput object can be found in the following schemas:

1. Item
2. Order
3. Feedback
4. CancellationTerm 

Usage in the Item schema:
Item:
    type: object
    properties:
        xinput:
            $ref: '#/components/schemas/XInput'
        ...

Usage in the Order schema:
Order:
    type: object
    properties:
        xinput:
            $ref: '#/components/schemas/XInput'
        ...

Usage in the Feedback schema:
Feedback:
    type: object
    properties:
        xinput:
            $ref: '#/components/schemas/XInput'
        ...

Usage in the CancellationTerm schema:
CancellationTerm:
    type: object
    properties:
        xinput:
            $ref: '#/components/schemas/XInput'
        ...

```

--------------------------------

### Bundle OpenAPI Specification

Source: https://github.com/beckn/protocol-specifications/blob/master/api/registry/README.md

Command to bundle the unresolved OpenAPI definition file (`api/registry/components/index.yaml`) into a single, resolved YAML file (`api/registry/build/registry.yaml`) using the swagger-cli.

```bash
swagger-cli bundle api/registry/components/index.yaml --outfile api/registry/build/registry.yaml --type yaml
```

--------------------------------

### BECKN Order Object with Form Data

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-007-The-XInput-Schema.md

Illustrates a BECKN protocol order object containing form details, including URL and MIME type, sent from BPP to BAP during the init action. This allows the BAP to fetch and render necessary forms for user input.

```json
{
   "context" : {
       "action" : "on_init",
       "..." : "// other context details"
   },
   "message" : {
       "order" : {
           "items" : [
               {
                   "id" : "4aa3feca-96b5-47dd-a233-f7fd2525922c",
                   "descriptor" : {
                       "name" : "Hyperlocal delivery"
                   },
                   "price" : {
                       "value" : "50",
                       "currency" : "INR"
                   }
               }
           ],
           "xinput" : {
               "form" : {
                   "url" : "https://api.example-bpp.com/getForm?id=t8923y4ryu328473y4",
                   "mime_type" : "text/html"
               }
           },
           "billing" : {
               "..." : "// billing details"
           },
           "fulfillment" : {
               "..." : "// fulfillment details"
           },
           "..." : "// other order level details"
       }
   }
}
```

--------------------------------

### Beckn Form Submission Process

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-007-The-XInput-Schema.md

Details the steps BAPs must follow for submitting form data, including identifying the submission URL from HTML or xForms and digitally signing the request body.

```apidoc
Beckn Form Submission:

1.  **Identify Submission URL**: 
    - For HTML forms: Extract from the `action` attribute of the `<form>` tag.
    - For xForms 2.0: Extract from the `action` attribute of the `<xforms:submission>` tag.

2.  **HTTP Method**: Typically POST.

3.  **Request Body**: Form data.

4.  **Security**: The request body MUST be digitally signed in the request header.

5.  **Example HTML Form Action**: 
    ```html
    <form action="http://example.com/submitForm" method="post">
      ...
    </form>
    ```

6.  **Example xForms Submission Action**: 
    ```xml
    <xforms:submission action="http://example.com/submitForm" method="post" id="submit" includenamespaceprefixes=""/>
    ```

7.  **Handling Responses**: 
    - Expect a `FormResponse` object containing `status`, `submission_id`, and `error` array.
    - If `FormResponse.status` is true, save `submission_id`.
    - If `FormResponse.status` is false, throw an exception based on the `error` object.

8.  **Post-Submission**: Send the `submission_id` in the `confirm` API's corresponding item's `xinput.form.submission_id` field.
```

--------------------------------

### BECKN Release Process and Voting

Source: https://github.com/beckn/protocol-specifications/blob/master/GOVERNANCE.md

Outlines the release process, including voting requirements and periods for patch, minor, and major releases, and potential overrides by WG Admin.

```APIDOC
Release Process:
  - Release requires a vote on release notes by CWG members within a specified voting period.
  - Announcements: Major/minor release voting periods announced by CWG admin in Slack and noted on the calendar at least 6 days in advance.
  - Approval: CWG members must note approval on the GitHub pull request for release notes.
  - Patch Releases: Happen at the first CWG meeting of a calendar month.
  - Coordination: CWG admin coordinates merge to main with marketing support.

Voting Policies:
  - Patch-level releases:
    - Approval: Majority approval by WG members.
    - Max voting period: 3 days.
  - Minor releases:
    - Approval: 66% of WG members.
    - Max voting period: 7 days.
  - Major releases:
    - Approval: 66% of WG members.
    - Max voting period: 14 days.

Override Clause:
  - A WG Admin may override majority and voting period based on area and group size.
```

--------------------------------

### OpenAPI Fulfillment Schema with Required Fields

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-001-Layering-Network-Policy-Draft-01.md

Illustrates how to add 'required' properties to OpenAPI schema definitions, specifically for the BECKN protocol's fulfillment domain. This example shows making the 'gps' coordinate a mandatory field within the 'location' object for mobility services, ensuring essential data is always present.

```APIDOC
FulfillmentPolicy1:
  description: Describes how a mobility service should be fulfilled
  type: object
  properties:
    id:
      type: string
      description: Unique reference ID to the fulfillment of an order
    type:
      type: string
      description: This describes the type of fulfillment
    provider_id:
      $ref: '#/components/schemas/Provider/properties/id'
    rating:
      $ref: '#/components/schemas/Rating/properties/value'
    state:
      $ref: '#/components/schemas/State'
    tracking:
      type: boolean
      description: Indicates whether the fulfillment allows tracking
      default: false
    customer:
      type: object
      properties:
        person:
          $ref: '#/components/schemas/Person'
        contact:
          $ref: '#/components/schemas/Contact'
    agent:
      $ref: '#/components/schemas/Agent'
    vehicle:
      $ref: '#/components/schemas/Vehicle'
    start:
      description: Details on the start of fulfillment
      type: object
      properties:
        location:
          allOf:
            - $ref: '#/components/schemas/Location'
            - required:
              - gps
        time:
          $ref: '#/components/schemas/Time'
        instructions:
          $ref: '#/components/schemas/Descriptor'
        contact:
          $ref: '#/components/schemas/Contact'
        person:
          $ref: '#/components/schemas/Person'
    end:
      description: Details on the end of fulfillment
      type: object
      properties:
        location:
          $ref: '#/components/schemas/Location'
        time:
          $ref: '#/components/schemas/Time'
        instructions:
          $ref: '#/components/schemas/Descriptor'
        contact:
          $ref: '#/components/schemas/Contact'
        person:
          $ref: '#/components/schemas/Person'
    rateable:
      $ref: '#/components/schemas/Rateable'
    tags:
      $ref: '#/components/schemas/Tags'
```

--------------------------------

### Mentee Information Request Form for Session Enrollment

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-007-The-XInput-Schema.md

This HTML form is used in a Beckn protocol education system. It allows mentors to request additional information from mentees before accepting enrollment requests. It collects details like bio, experience, recommendation letters, and degree using various input types.

```html
<form action="https://api.example-bpp.com/sendMenteeInformation" method="post">
        <label for="resume">Bio of Mentee</label>
        <input type="file" id="resume" name="resume" multiple="true" />
        <label for="experience">Experience in No Of Years </label>
        <input type="text" id="experience" name="experience" value="0" />
        <label for="recommendationLetter">Recommendation Letter from any organisation</label>
        <input type="file" id="recommendationLetter" name="recommendationLetter" multiple="false" />
        <label for="degree">Select your degree</label>
        <select name="degree" id="degree">
            <option value="BTECH">Btech in Computer Science</option>
            <option value="PHD">PHD in Computer Science</option>
            <option value="MS">Masters in Computer Science</option>
        </select>
        <input type="hidden" id="nonce" name="nonce" value="t8923y4ryu328473y4" />
   </form>
```

--------------------------------

### Beckn Gateway with Registry Lookup

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-003-Beckn-Protocol-Communication-Draft-01.md

Explains the communication flow when a Beckn Gateway (BG) uses a Registry to discover BPP addresses. The BG queries the Registry, then multicasts the message to the identified BPPs, adhering to the standard asynchronous ACK and callback pattern.

```APIDOC
Scenario: BAP to BG to Registry to BPP Communication

1. BAP calls BG.
2. BG queries the Registry via the 'lookup' API to get BPP addresses.
3. BG multicasts the message to the discovered BPPs.
4. BPPs respond with ACKs.
5. BPPs asynchronously call the 'on_search' API (or relevant callback) back to the BAP.
```

--------------------------------

### OpenAPI Payment Schema Alternatives

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-001-Layering-Network-Policy-Draft-01.md

Demonstrates using OpenAPI's 'oneOf' or 'allOf' keywords to define multiple alternative schemas for payment parameters. This allows for flexibility in supporting various payment methods like Bank Transfer, Unified Payment Interface (UPI), and Payment Gateways within a single schema definition.

```APIDOC
PaymentParams:
  type: object
  properties:
    transaction_id:
      type: string
    transaction_status:
      type: string
    amount:
      $ref: '#/components/schemas/Price/properties/value'
    currency:
      $ref: '#/components/schemas/Price/properties/currency'
  required:
    - currency
    - amount

PaymentParamsPolicy1:
  allOf:
    - $ref: '#/components/schemas/PaymentParams'
    - type: object
      properties:
        anyOf:
          - $ref: '#/components/schemas/BankTransfer'
          - $ref: '#/components/schemas/UnifiedPaymentInterface'
          - $ref: '#/components/schemas/PaymentGatewayParams'

BankTransfer:
  type: object
  properties:
    account_name:
      type: string
    account_id:
      type: string
    ifsc:
      type: string

UnifiedPaymentInterface:
  type: object
  properties:
    vpa:
      type: string

PaymentGatewayParams:
  type: object
  properties:
    merchant_id:
      type: string
    redirect_uri:
      type: string
```

--------------------------------

### BG Request Signing for BPP Communication

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP-Draft-01.md

Details the steps the BG takes to sign outgoing requests before forwarding them to a BPP, creating the `X-Gateway-Authorization` header to ensure message integrity and authenticity.

```APIDOC
BG Signing Process:
  - BG uses its own signing keys (private_key).
  - Example BG Signing Keys:
    signing_public_key=7YRZXVeIJ0/Va56vYgzT1Uirg6mnq3FY0MBZY9DJft0=
    signing_private_key=hJ5sCmbe7s9Wateq6QAdBGloVSkLuLHWOXcRkzrMcVLthFldV4gnT9Vrnq9iDNPVSKuDqaercVjQwFlj0Ml+3Q==

Steps:
1.  Generate Digest:
    - Digest of the request body using BLAKE-512 hashing.
    - Example Digest: `b6lf6lRgOweajukcvcLsagQ2T60+85kRh/Rd2bdS+TG/5ALebOEgDJfyCrre/1+BMu5nA94o4DT3pTFXuUg7sw==`

2.  Generate `created` field:
    - Unix timestamp integer value indicating when the signature was created.
    - Must not be in the future.
    - Example: `(created): 1641287885`

3.  Generate `expires` field:
    - Unix timestamp integer value indicating when the signature ceases to be valid.
    - Must not be in the past.
    - Example: `(expires): 1641291485`

4.  Create Signing String:
    - Concatenate `created`, `expires`, and `digest`.
    - Format:
      (created): {created_timestamp}
      (expires): {expires_timestamp}
      digest: {algorithm}={digest_value}
    - Example Signing String:
      (created): 1641287885
      (expires): 1641291485
      digest: BLAKE-512=b6lf6lRgOweajukcvcLsagQ2T60+85kRh/Rd2bdS+TG/5ALebOEgDJfyCrre/1+BMu5nA94o4DT3pTFXuUg7sw==

5.  Sign the String:
    - Use BG's registered signing private key (e.g., Ed25519 Signature Scheme).

6.  Base64 Encode Signature:
    - Generate a base64 encoded string of the signature.
    - Example Signature: `hJ5sCmbe7s9Wateq6QAdBGloVSkLuLHWOXcRkzrMcVLthFldV4gnT9Vrnq9iDNPVSKuDqaercVjQwFlj0Ml+3Q==`

7.  Construct `X-Gateway-Authorization` Header:
    - Format:
      Signature keyId="{bg_subscriber_id}|{bg_unique_key_id}|{bg_algorithm}",algorithm="{bg_algorithm}",created="{created_timestamp}",expires="{expires_timestamp}",headers="(created) (expires) digest",signature="{base64_signature}"
    - Example Header (assuming `subscriber_id` = example-bg.com, `unique_key_id` = dfb974ea-9113-4089-9a2d-77552b50624e):
      Signature keyId="example-bg.com|dfb974ea-9113-4089-9a2d-77552b50624e|ed25519",algorithm="ed25519",created="1641287885",expires="1641287885",headers="(created) (expires) digest",signature="hJ5sCmbe7s9Wateq6QAdBGloVSkLuLHWOXcRkzrMcVLthFldV4gnT9Vrnq9iDNPVSKuDqaercVjQwFlj0Ml+3Q=="

8.  Include Header in Request:
    - BG includes the `X-Gateway-Authorization` header when calling the BPP search API.

Notes on `created` and `expires`:
  - The difference between `created` and `expires` should equal the request's TTL.
  - `expires` value should not exceed the expiration time of the signing key.
```

--------------------------------

### BECKN Transparency and Participation Guidelines

Source: https://github.com/beckn/protocol-specifications/blob/master/GOVERNANCE.md

Describes principles for transparency in discussions and encourages broad community participation in the specification's evolution.

```APIDOC
Transparency:
  - Process should be as transparent as possible.
  - Sensitive discussions (customer names, use cases) must be anonymized, discussed in a private repository, or conducted offline.
  - General discussions should occur on GitHub issues.

Participation:
  - Governance: Role of the CWG.
  - Evolution: Happens through participation of the developer community at large.
  - Contribution Methods: Filing/participating in issues, creating pull requests, helping others.
```

--------------------------------

### OpenAPI: Schema Inheritance with allOf

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-001-Layering-Network-Policy-Draft-01.md

Demonstrates how to use the OpenAPI 3.1.0 'allOf' keyword to combine schemas, allowing for inheritance of properties. This is useful for composing complex data models from common base schemas and specific extensions.

```yaml
components:
  schemas:
    Tags:
      type: object

    CategoryTags:
      allOf:
        - $ref: '#/components/schemas/Tags'
        - type: object
          properties:
            brand:
              type: string
              enum:
                - brand
                - purpose
                - season
```

```yaml
ContextPolicy1:
  description: Describes the context policy of a message on this network
  allOf:
  - $ref: '#/components/schemas/Context'
  - type: object
    properties:
        action:
           type: string
           description: Actions supported by this policy
           enum:
             - search
             - confirm
             - on_search
             - on_confirm
       core_version:
           type: string
           description: Specification versions supported by this policy
           enum:
             - '0.9.1'
             - '0.9.2'
             - '0.9.3-draft'
           default: 0.9.2
       ttl:
           type: string
           description: TTL of the message
           minimum: P0S
           maximum: P1M
```

```yaml
RatingPolicy1:
  description: Describes the context policy of a message on this network
  allOf:
  - $ref: '#/components/schemas/Rating'
  - type: object
    properties:
        value:
           type: number
           minimum: 1
           maximum: 10
```

--------------------------------

### BAP Signature Verification by BG

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP-Draft-01.md

Details the steps the BG performs to authenticate the BAP and ensure message integrity. This involves parsing the Authorization header, retrieving the BAP's public key, and verifying the signature.

```APIDOC
Authorization Header Parsing:
  - BG extracts `keyId` from the `Authorization` header.
  - `keyId` format: `{subscriber id}|{unique_key_id}|{signing algorithm}`
  - Example `keyId`: `example-bap.com|ae3ea24b-cfec-495e-81f8-044aaef164ac|ed25519`
  - The `unique_key_id` is used when a BAP has multiple public keys registered.
  - If the signing algorithm in `keyId` does not match the `algorithm` parameter in the Authorization header, return 401 Unauthorized.

Public Key Retrieval:
  - BG looks up the BAP's public key using `subscriber_id` and `unique_key_id` via a `lookup` API or cached copy.
  - Example Public Key: `awGPjRK6i/Vg/lWr+0xObclVxlwZXvTjWYtlu6NeOHk=`
  - If no valid key is found, return NACK with 401 Unauthorized.

Signature Verification:
  - BG uses the retrieved BAP's public key to verify the signature.
  - If signature is verified, BAP is authenticated.
  - If not verified, return NACK with 401 Unauthorized and a `WWW-Authenticate` header.

Error Response Example (Invalid Signature):
  Headers:
    HTTP/1.1 401 Unauthorized
    WWW-Authenticate: Signature realm="example-bg.com",headers="(created) (expires) digest"
  Request Body:
    {
        "message": {
            "ack": {
                "status": "NACK"
            }
        }
    }

Note on `unique_key_id`:
  - If network policy allows only one key-pair per subscriber, `unique_key_id` is NOT NEEDED in `keyId`.
```

--------------------------------

### BG Callback Signing Header Generation

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP-Draft-01.md

Describes the process for the BG to generate the X-Gateway-Authorization header for outgoing requests to the BAP. This involves hashing the request body, creating timestamp fields, signing the concatenated string, and encoding the signature.

```APIDOC
Signing String Format:
(created): {unix_timestamp}
(expires): {unix_timestamp}
digest: {algorithm}={base64_encoded_digest}

Example X-Gateway-Authorization Header:
Signature keyId="{subscriber_id}|{unique_key_id}|{signing_algorithm}",algorithm="{signing_algorithm}",created="{created_timestamp}",expires="{expires_timestamp}",headers="(created) (expires) digest",signature="{base64_encoded_signature}"
```

```APIDOC
Example Header Values:
keyId="example-bg.com|dfb974ea-9113-4089-9a2d-77552b50624e|ed25519"
algorithm="ed25519"
created="1641287885"
expires="1641287885"
headers="(created) (expires) digest"
signature="hJ5sCmbe7s9Wateq6QAdBGloVSkLuLHWOXcRkzrMcVLthFldV4gnT9Vrnq9iDNPVSKuDqaercVjQwFlj0Ml+3Q=="
```

--------------------------------

### OpenAPI: Applying Constraints (enum, default, min/max)

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-001-Layering-Network-Policy-Draft-01.md

Illustrates how to apply specific constraints like enumerations, default values, minimum, and maximum values to schema properties within an OpenAPI 3.1.0 specification. This allows for network-specific policy enforcement on data attributes.

```yaml
ContextPolicy1:
  description: Describes the context policy of a message on this network
  allOf:
  - $ref: '#/components/schemas/Context'
  - type: object
    properties:
        action:
           type: string
           description: Actions supported by this policy
           enum:
             - search
             - confirm
             - on_search
             - on_confirm
       core_version:
           type: string
           description: Specification versions supported by this policy
           enum:
             - '0.9.1'
             - '0.9.2'
             - '0.9.3-draft'
           default: 0.9.2
       ttl:
           type: string
           description: TTL of the message
           minimum: P0S
           maximum: P1M
```

```yaml
RatingPolicy1:
  description: Describes the context policy of a message on this network
  allOf:
  - $ref: '#/components/schemas/Rating'
  - type: object
    properties:
        value:
           type: number
           minimum: 1
           maximum: 10
```

--------------------------------

### BECKN Pull Request Workflow

Source: https://github.com/beckn/protocol-specifications/blob/master/GOVERNANCE.md

Details the required process for submitting and reviewing pull requests, including issue linking and handling of unlinked PRs.

```APIDOC
Pull Request (PR) Workflow:
  1. PR Requirement: Every PR must have an associated Issue.
  2. Unlinked PRs: If no Issue is present, the reviewer must comment requesting the contributor to Raise an Issue and link the PR.
  3. PR Rejection (Unlinked Issue): If an Issue is not raised within 24 hours, the PR is considered rejected and closed with the comment: “Closing this due to unlinked Issue”.
  4. PR Purpose: A PR describes the _proposed_ solution and links to the original issue.
  5. Parallel Efforts: Multiple proposals can be open and worked on in parallel.
```

--------------------------------

### Beckn Protocol Form Handling API Specification

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-007-The-XInput-Schema.md

Details the expected behavior and requirements for handling form submissions within the Beckn protocol. This includes security checks, nonce validation, input validation, and response generation.

```APIDOC
Beckn Form Submission Handling:

When a BAP submits form data to a BPP via HTTP/POST:

1.  **Signature Verification**: The BPP must verify the digital signature of the submission request sent by the BAP.
2.  **Nonce Validation**: The BPP must check if a unique nonce value (in UUID format) exists and has not expired. This nonce should have been previously sent by the BPP to the BAP.
3.  **Input Validation**: If the nonce is valid and not expired, the BPP must validate the submitted form inputs.
4.  **Response Generation**: Upon successful validation, the BPP must generate a `FormResponse` object and return it as an `application/json` response.

**Security Recommendations**:
- Form submission URLs should ideally be on the same domain as the BPP's subscriber_id to mitigate security errors.
- BPPs should persist the nonce value until a submission matches it or the form expires.

**FormResponse Object Structure**:
(Details of FormResponse object structure would typically be defined here, e.g., fields like `submission_id`, `status`, `errors`)

**Linking Submissions to Transactions**:
- Submissions are linked to transactions via `submission_id` fields found in `Order.items[].xinput_required.form.submission_id` and `Order.xinput_required.form.submission_id`.

**Discarding Submissions**:
- BPPs may discard form submissions if a corresponding confirm API call is not received within a specified time window after submission.
```

--------------------------------

### BPP Transaction API Endpoints

Source: https://github.com/beckn/protocol-specifications/blob/master/api/transaction/components/io/README.md

Specifies the Transaction API endpoints for the Business Partner Platform (BPP). This includes core actions like search, select, init, confirm, status, update, track, cancel, rating, and support.

```APIDOC
BPP API Endpoints:

- search: Search.yaml
- select: Select.yaml
- init: Init.yaml
- confirm: Confirm.yaml
- status: Status.yaml
- update: Update.yaml
- track: Track.yaml
- cancel: Cancel.yaml
- rating: Rating.yaml
- support: Support.yaml
```

--------------------------------

### Beckn Asynchronous API Communication Pattern

Source: https://github.com/beckn/protocol-specifications/blob/master/README.md

Describes the asynchronous server-to-server communication pattern in Beckn, where an initial API call receives an ACK, followed by a later callback API response.

```APIDOC
Asynchronous API Call Pattern:
  Sender calls API (e.g., search)
    - Receiver responds with ACK (acknowledgment) and closes session.
  Receiver calls back API (e.g., on_search)
    - Sender implements callback API to receive the actual response.

Example Flow:
  1. BAP server sends a 'search' request to a BPP server.
  2. BPP server validates the request, sends an ACK back to BAP, and closes the session.
  3. BPP server processes the search request asynchronously.
  4. BPP server sends the search results via an 'on_search' callback API to the BAP server.
```

--------------------------------

### Rating Ledger API Actions

Source: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-008-Rating-and-Reputation-on-Beckn-Protocol.md

Details the primary API actions for interacting with the Rating Ledger. These actions facilitate the submission of bulk ratings and the verification of entity ratings.

```APIDOC
RatingReceiverAPI:
  Actions:
    - rating_action: Used by a Rating Sender to submit rating information to the Rating Receiver. This action can receive bulk rating information.

RatingLedgerAPI:
  Actions:
    - lookup_action: Used by a Rating Sender to verify the rating of a Rateable Entity. Requires the Rateable Entity's ID.
    - bulk_rating_submission: (Implied by rating_action description) Mechanism for sending multiple ratings periodically (e.g., daily) to update the Rating Ledger.
```

--------------------------------

### BECKN Protocol Branching Model

Source: https://github.com/beckn/protocol-specifications/blob/master/GOVERNANCE.md

Defines the standard Git branch structure for managing the BECKN protocol specifications, including stable, draft, and future version branches.

```APIDOC
Branch Structure:
  - master: Current stable version. No direct PRs accepted for specification changes; PRs for supporting files are allowed.
  - core-X.Y.Z-draft: Next PATCH version. Includes non-breaking changes (typo fixes, document clarifications).
  - core-X.Y.Z-draft: Next MINOR version. Includes backward-compatible changes (e.g., attributes to existing schemas).
  - core-X.Y.Z-draft: Next MAJOR version.

Branching Policy:
  - At most 4 working branches should exist simultaneously.
  - master branch remains the current, released specification.
  - Working branches are described and linked on the default README.md on main.
```