3380 lines
123 KiB
YAML
3380 lines
123 KiB
YAML
openapi: 3.1.1
|
|
info:
|
|
title: Beckn Protocol API
|
|
description: |
|
|
The Beckn Protocol API Specification v2.0 — a concrete, developer-friendly OpenAPI 3.1.1
|
|
specification with one named path per Beckn protocol action.
|
|
|
|
## Design Philosophy
|
|
- **Minimalism**: Transport-layer schemas are inline. All data-model schemas
|
|
(Catalog, Contract, Intent, etc.) are resolved from #/components/schemas.
|
|
- **Pragmatism**: Every transaction endpoint carries both `order` (legacy, backward-compatible)
|
|
and `contract` (new, generalized) in its message envelope via `oneOf`.
|
|
- **Backward compatibility**: Implementations conformant with previous versions interoperate
|
|
seamlessly with new implementations using the `contract` model.
|
|
|
|
## Typical Transaction Lifecycle
|
|
```
|
|
discover → on_discover
|
|
select → on_select → init → on_init → confirm → on_confirm
|
|
→ [status / on_status]* → [update / on_update]* → [cancel / on_cancel]?
|
|
→ [track / on_track]* → rate / on_rate → support / on_support
|
|
```
|
|
|
|
## (NEW) `context.try` — Sandbox Mode
|
|
The `try` flag on the `Context` object (defined in `#/components/schemas/Context`)
|
|
indicates a sandbox mode being enabled on the network participant:
|
|
- `context.try: true` — Request to test an endpoint without liabilities
|
|
**before** committing. The receiver responds with expected consequences without changing state.
|
|
- `context.try: false` (default) — Commit the action.
|
|
This pattern is applicable to `update`, `cancel`, `rate`, and `support` actions.
|
|
|
|
## Authentication
|
|
All requests MUST carry a valid Beckn HTTP Signature in the `Authorization` header.
|
|
The `Ack` response body MUST carry a `CounterSignature` proving receipt.
|
|
See `docs/10_Signing_Beckn_APIs_in_HTTP.md` for the signing specification.
|
|
|
|
## Compatibility Scope
|
|
This specification is designed for interoperability across ALL value-exchange use cases:
|
|
retail, mobility, logistics, energy, healthcare, skilling, financial services,
|
|
carbon trading, hiring, data licensing, and any other domain built on Beckn.
|
|
version: 2.0.0
|
|
contact:
|
|
name: Beckn Protocol
|
|
url: https://beckn.io
|
|
license:
|
|
name: CC-BY-NC-SA 4.0 International
|
|
url: https://creativecommons.org/licenses/by-nc-sa/4.0/deed.en
|
|
|
|
tags:
|
|
- name: Discovery
|
|
description: Discover catalogs across a Beckn network
|
|
- name: Transaction
|
|
description: Select, negotiate, confirm and manage contracts/orders
|
|
- name: Fulfillment
|
|
description: Track, update and cancel active contracts/orders
|
|
- name: Post-Fulfillment
|
|
description: Rate and support completed contracts/orders
|
|
- name: Catalog Publishing
|
|
description: Publish catalogs to a Catalog Discovery Service (CDS)
|
|
|
|
# All requests MUST carry a valid Beckn HTTP Signature in the Authorization header.
|
|
# The securityScheme is informational; actual enforcement is done at the network layer.
|
|
security: []
|
|
|
|
paths:
|
|
|
|
# ─────────────────────────────────────────────────────────────────────
|
|
# DISCOVERY
|
|
# ─────────────────────────────────────────────────────────────────────
|
|
|
|
/discover:
|
|
post:
|
|
summary: Discover catalogs on a network
|
|
description: |
|
|
Search and discover catalogs on an open network. Supports text search (textSearch),
|
|
JSONPath-based filtering (RFC 9535), spatial (geo) constraints, and media search.
|
|
Returns an **ACK** confirming receipt; actual catalogs arrive via `/beckn/on_discover`.
|
|
Can be implemented by Catalog Discovery Services (CDS) and BPPs.
|
|
operationId: discover
|
|
tags: [Discovery]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Context' # TODO: fetch this from schema.beckn.io/Context/v2.0
|
|
- type: object
|
|
properties:
|
|
action:
|
|
type: string
|
|
const: discover
|
|
message:
|
|
$ref: '#/components/schemas/DiscoverAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'409':
|
|
$ref: '#/components/responses/AckNoCallback'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/on_discover:
|
|
post:
|
|
summary: Callback — return catalogs to the BAP
|
|
description: |
|
|
Callback from a BPP or CDS containing catalogs matching the discovery request.
|
|
Returns an **ACK** confirming receipt of the catalog payload.
|
|
operationId: onDiscover
|
|
tags: [Discovery]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Context'
|
|
- type: object
|
|
properties:
|
|
action:
|
|
type: string
|
|
const: on_discover
|
|
message:
|
|
$ref: '#/components/schemas/OnDiscoverAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
# ─────────────────────────────────────────────────────────────────────
|
|
# TRANSACTION — ORDERING
|
|
# ─────────────────────────────────────────────────────────────────────
|
|
|
|
/select:
|
|
post:
|
|
summary: BAP selects items/resources and requests a quote
|
|
description: |
|
|
The BAP selects catalog items, item quantities, associated offers, and requests
|
|
the BPP to provide a priced quote. No PII is shared at this stage.
|
|
Supports both the legacy `order` and the new `contract` model.
|
|
operationId: select
|
|
tags: [Transaction]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Context'
|
|
- type: object
|
|
properties:
|
|
action:
|
|
type: string
|
|
const: select
|
|
message:
|
|
$ref: '#/components/schemas/SelectAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'409':
|
|
$ref: '#/components/responses/AckNoCallback'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/on_select:
|
|
post:
|
|
summary: BPP returns a priced quote
|
|
description: |
|
|
The BPP calculates the total cost, evaluates offers, and returns a priced quote.
|
|
Supports both the legacy `order` model and the new `contract` model.
|
|
operationId: onSelect
|
|
tags: [Transaction]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Context'
|
|
- type: object
|
|
properties:
|
|
action:
|
|
type: string
|
|
const: on_select
|
|
message:
|
|
$ref: '#/components/schemas/OnSelectAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/init:
|
|
post:
|
|
summary: BAP initiates final order — submits billing, fulfillment and payment intent
|
|
description: |
|
|
BAP provides billing, fulfillment, and payment information for the BPP to generate
|
|
final order terms. The BPP responds via `on_init` with the final draft including
|
|
payment terms. Supports both `order` (legacy) and `contract` (new) models.
|
|
operationId: init
|
|
tags: [Transaction]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Context'
|
|
- type: object
|
|
properties:
|
|
action:
|
|
type: string
|
|
const: init
|
|
message:
|
|
$ref: '#/components/schemas/InitAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'409':
|
|
$ref: '#/components/responses/AckNoCallback'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/on_init:
|
|
post:
|
|
summary: BPP returns final draft order/contract with payment terms
|
|
description: |
|
|
BPP returns the final draft order or contract with personalized payment terms.
|
|
The BPP MUST NOT request payment before this stage.
|
|
operationId: onInit
|
|
tags: [Transaction]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Context'
|
|
- type: object
|
|
properties:
|
|
action:
|
|
type: string
|
|
const: on_init
|
|
message:
|
|
$ref: '#/components/schemas/OnInitAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/confirm:
|
|
post:
|
|
summary: BAP confirms the order/contract
|
|
description: |
|
|
BAP accepts all terms and provides payment proof/reference, then requests the BPP
|
|
to confirm the order or contract into a binding commitment.
|
|
operationId: confirm
|
|
tags: [Transaction]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Context'
|
|
- type: object
|
|
properties:
|
|
action:
|
|
type: string
|
|
const: confirm
|
|
message:
|
|
$ref: '#/components/schemas/ConfirmAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'409':
|
|
$ref: '#/components/responses/AckNoCallback'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/on_confirm:
|
|
post:
|
|
summary: BPP returns the confirmed order/contract
|
|
description: |
|
|
BPP validates all terms, payment, and returns a confirmed order or contract with
|
|
its assigned ID and the initial fulfillment/performance state.
|
|
operationId: onConfirm
|
|
tags: [Transaction]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Context'
|
|
- type: object
|
|
properties:
|
|
action:
|
|
type: string
|
|
const: on_confirm
|
|
message:
|
|
$ref: '#/components/schemas/OnConfirmAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
# ─────────────────────────────────────────────────────────────────────
|
|
# FULFILLMENT
|
|
# ─────────────────────────────────────────────────────────────────────
|
|
|
|
/status:
|
|
post:
|
|
summary: BAP requests the current state of an order/contract
|
|
description: |
|
|
BAP requests the latest state of an active order or contract by providing its ID.
|
|
The BPP responds via `on_status`. BAPs SHOULD NOT long-poll with `status` —
|
|
use `on_status` push notifications for significant state changes.
|
|
operationId: status
|
|
tags: [Fulfillment]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Context'
|
|
- type: object
|
|
properties:
|
|
action:
|
|
type: string
|
|
const: status
|
|
message:
|
|
$ref: '#/components/schemas/StatusAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'409':
|
|
$ref: '#/components/responses/AckNoCallback'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/on_status:
|
|
post:
|
|
summary: BPP returns the current state of the order/contract
|
|
description: |
|
|
BPP returns the latest state of the order or contract including fulfillment/performance
|
|
updates. The BPP MAY call this endpoint proactively without the BAP requesting it,
|
|
but MUST have received at least one `status` request first to initiate the push stream.
|
|
This endpoint is for significant state changes worth a notification — NOT for
|
|
real-time location tracking (use `track`/`on_track` for that).
|
|
operationId: onStatus
|
|
tags: [Fulfillment]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Context'
|
|
- type: object
|
|
properties:
|
|
action:
|
|
type: string
|
|
const: on_status
|
|
message:
|
|
$ref: '#/components/schemas/OnStatusAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/track:
|
|
post:
|
|
summary: BAP requests a real-time tracking handle for an active order/contract
|
|
description: |
|
|
BAP requests a tracking handle (URL, WebSocket endpoint, or webhook) for real-time
|
|
tracking of an active fulfillment or performance stage. This is for real-time
|
|
position/progress updates — NOT for order state change notifications (use `status`).
|
|
operationId: track
|
|
tags: [Fulfillment]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Context'
|
|
- type: object
|
|
properties:
|
|
action:
|
|
type: string
|
|
const: track
|
|
message:
|
|
$ref: '#/components/schemas/TrackAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'409':
|
|
$ref: '#/components/responses/AckNoCallback'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/on_track:
|
|
post:
|
|
summary: BPP returns real-time tracking handle and status
|
|
operationId: onTrack
|
|
tags: [Fulfillment]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Context'
|
|
- type: object
|
|
properties:
|
|
action:
|
|
type: string
|
|
const: on_track
|
|
message:
|
|
$ref: '#/components/schemas/OnTrackAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/update:
|
|
post:
|
|
summary: BAP requests a mutation to an active order/contract
|
|
description: |
|
|
BAP requests the BPP to update an active order or contract. Updates may involve
|
|
change of items, quantities, billing, fulfillment/performance, or payment.
|
|
|
|
Uses the `context.try` two-phase pattern (defined in `Context` schema):
|
|
- `context.try: true` — BAP requests updated terms before committing (preview mode).
|
|
BPP responds with recalculated quote and terms via `on_update` without changing state.
|
|
- `context.try: false` (default) — BAP commits the update.
|
|
BPP responds with the confirmed updated order/contract.
|
|
operationId: update
|
|
tags: [Fulfillment]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
$ref: '#/components/schemas/Context'
|
|
message:
|
|
$ref: '#/components/schemas/UpdateAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'409':
|
|
$ref: '#/components/responses/AckNoCallback'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/on_update:
|
|
post:
|
|
summary: BPP returns the updated order/contract
|
|
description: |
|
|
BPP returns the updated order or contract with recalculated terms. Can be called
|
|
proactively by the BPP without the BAP requesting it.
|
|
- If `context.try: true` — returns updated terms (preview; state not changed).
|
|
- If `context.try: false` — returns committed updated order/contract.
|
|
operationId: onUpdate
|
|
tags: [Fulfillment]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
$ref: '#/components/schemas/Context'
|
|
message:
|
|
$ref: '#/components/schemas/OnUpdateAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/cancel:
|
|
post:
|
|
summary: BAP requests cancellation of an order/contract
|
|
description: |
|
|
BAP requests full or partial cancellation. Uses the `context.try` two-phase pattern:
|
|
- `context.try: true` — BAP requests cancellation terms (e.g., refund policy, penalty)
|
|
without committing to cancellation. BPP responds with applicable policy via `on_cancel`.
|
|
- `context.try: false` (default) — BAP commits the cancellation.
|
|
BPP confirms cancellation and returns cancelled order/contract.
|
|
operationId: cancel
|
|
tags: [Fulfillment]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
$ref: '#/components/schemas/Context'
|
|
message:
|
|
$ref: '#/components/schemas/CancelAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'409':
|
|
$ref: '#/components/responses/AckNoCallback'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/on_cancel:
|
|
post:
|
|
summary: BPP returns cancellation terms or confirms cancellation
|
|
description: |
|
|
- If `context.try: true` — returns applicable cancellation policy, fees, refund timeline
|
|
(state not changed).
|
|
- If `context.try: false` — returns confirmed cancelled order/contract with refund/payment update.
|
|
operationId: onCancel
|
|
tags: [Fulfillment]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
$ref: '#/components/schemas/Context'
|
|
message:
|
|
$ref: '#/components/schemas/OnCancelAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
# ─────────────────────────────────────────────────────────────────────
|
|
# POST-FULFILLMENT
|
|
# ─────────────────────────────────────────────────────────────────────
|
|
|
|
/rate:
|
|
post:
|
|
summary: BAP submits ratings for one or more entities
|
|
description: |
|
|
BAP submits ratings for any ratable entity (order, contract, fulfillment,
|
|
item, provider, agent, support interaction). Supports the `context.try` pattern:
|
|
- `context.try: true` — Preview: BPP returns the rating form/criteria without recording.
|
|
- `context.try: false` (default) — Submit: BPP records the rating and returns confirmation.
|
|
The BPP acknowledges via `on_rate` with an optional aggregate snapshot.
|
|
operationId: rate
|
|
tags: [Post-Fulfillment]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
$ref: '#/components/schemas/Context'
|
|
message:
|
|
$ref: '#/components/schemas/RateAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'409':
|
|
$ref: '#/components/responses/AckNoCallback'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/on_rate:
|
|
post:
|
|
summary: BPP acknowledges rating and optionally returns aggregate
|
|
description: |
|
|
- If `context.try: true` — returns rating form/criteria (preview mode).
|
|
- If `context.try: false` — confirms rating was recorded; optionally returns aggregate.
|
|
operationId: onRate
|
|
tags: [Post-Fulfillment]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
$ref: '#/components/schemas/Context'
|
|
message:
|
|
$ref: '#/components/schemas/OnRateAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/support:
|
|
post:
|
|
summary: BAP requests support information for an entity
|
|
description: |
|
|
BAP requests support channels and/or raises a support ticket for any entity.
|
|
Uses the `context.try` pattern:
|
|
- `context.try: true` — Preview: BPP returns available support channels without creating a ticket.
|
|
- `context.try: false` (default) — BAP submits a support request; BPP creates/links a ticket.
|
|
The `refType` field abstracts over domain-specific entity types (works for contracts,
|
|
resources, providers, agents — not just orders).
|
|
operationId: support
|
|
tags: [Post-Fulfillment]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
$ref: '#/components/schemas/Context'
|
|
message:
|
|
$ref: '#/components/schemas/SupportAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'409':
|
|
$ref: '#/components/responses/AckNoCallback'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/on_support:
|
|
post:
|
|
summary: BPP returns support details
|
|
description: |
|
|
- If `context.try: true` — returns available support channels (preview mode).
|
|
- If `context.try: false` — returns support details with ticket(s).
|
|
operationId: onSupport
|
|
tags: [Post-Fulfillment]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
$ref: '#/components/schemas/Context'
|
|
message:
|
|
$ref: '#/components/schemas/OnSupportAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
# ─────────────────────────────────────────────────────────────────────
|
|
# CATALOG PUBLISHING SERVICE
|
|
# ─────────────────────────────────────────────────────────────────────
|
|
|
|
/catalog/publish:
|
|
post:
|
|
summary: BPP publishes catalogs for indexing by a CDS
|
|
description: |
|
|
BPP submits one or more catalogs to be indexed by a Catalog Discovery Service (CDS).
|
|
Returns an **ACK** immediately if accepted for processing. The per-catalog processing
|
|
result arrives asynchronously via `/beckn/catalog/on_publish`.
|
|
operationId: catalogPublish
|
|
tags: [Catalog Publishing]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Context'
|
|
- type: object
|
|
properties:
|
|
action:
|
|
type: string
|
|
const: catalog/publish
|
|
message:
|
|
$ref: '#/components/schemas/CatalogPublishAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'409':
|
|
$ref: '#/components/responses/AckNoCallback'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/catalog/on_publish:
|
|
post:
|
|
summary: CDS returns per-catalog processing results to the BPP
|
|
operationId: catalogOnPublish
|
|
tags: [Catalog Publishing]
|
|
parameters:
|
|
- $ref: '#/components/parameters/AuthorizationHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
context:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Context'
|
|
- type: object
|
|
properties:
|
|
action:
|
|
type: string
|
|
const: catalog/on_publish
|
|
message:
|
|
$ref: '#/components/schemas/CatalogPublishAction'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Ack'
|
|
'400':
|
|
$ref: '#/components/responses/NackBadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/NackUnauthorized'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
# ─────────────────────────────────────────────────────────────────────
|
|
# COMPONENTS
|
|
# ─────────────────────────────────────────────────────────────────────
|
|
components:
|
|
|
|
# ─── Parameters ──────────────────────────────────────────────────
|
|
parameters:
|
|
AuthorizationHeader:
|
|
name: Authorization
|
|
in: header
|
|
required: true
|
|
description: |
|
|
Beckn HTTP Signature authentication header.
|
|
See `#/components/schemas/Signature` for the expected format.
|
|
schema:
|
|
$ref: '#/components/schemas/Signature'
|
|
|
|
# ─── Message Schemas ──────────────────────────────────────────────
|
|
|
|
schemas:
|
|
# ─────────────────────────────────────────────────────────────────────
|
|
# ACTION SCHEMAS — xAction and On-xAction message payloads
|
|
# ─────────────────────────────────────────────────────────────────────
|
|
CancelAction:
|
|
$id: https://schema.beckn.io/CancelAction/v2.0
|
|
title: Cancel Action
|
|
description: |
|
|
Beckn /beckn/cancel message payload. Sent by a BAP to a BPP to request
|
|
cancellation of an active contract. Set context.try to true to first
|
|
retrieve cancellation terms and fees before committing.
|
|
(Context wrapper stripped; only the message-content portion is inlined.)
|
|
oneOf:
|
|
- type: object
|
|
required: [order]
|
|
properties:
|
|
order:
|
|
type: object
|
|
- type: object
|
|
required: [contract]
|
|
properties:
|
|
contract:
|
|
$ref: '#/components/schemas/Contract'
|
|
|
|
CatalogPublishAction:
|
|
$id: https://schema.beckn.io/CatalogPublishAction/v2.0
|
|
description: Catalog publish request payload.
|
|
type: object
|
|
required: [catalogs]
|
|
properties:
|
|
catalogPublishAttributes:
|
|
type: object
|
|
description: Domain-specific extension attributes for this catalog publish action.
|
|
properties:
|
|
'@context':
|
|
type: array
|
|
items:
|
|
type: string
|
|
format: uri
|
|
uniqueItems: true
|
|
contains:
|
|
const: 'https://schema.beckn.io/CatalogPublishAction/v2.0/context.jsonld'
|
|
minItems: 1
|
|
'@type':
|
|
type: array
|
|
items:
|
|
type: string
|
|
format: uri
|
|
uniqueItems: true
|
|
contains:
|
|
const: 'beckn:CatalogPublishAction'
|
|
minItems: 1
|
|
catalogs:
|
|
type: array
|
|
minItems: 1
|
|
description: One or more catalogs to be indexed by the CDS
|
|
items:
|
|
$ref: '#/components/schemas/Catalog'
|
|
|
|
OnCatalogPublishAction:
|
|
$id: https://schema.beckn.io/CatalogPublishResponse/v2.0
|
|
type: object
|
|
required: [context, message]
|
|
properties:
|
|
onCatalogPublishAttributes:
|
|
type: object
|
|
description: Domain-specific extension attributes for this on_catalog_publish action.
|
|
properties:
|
|
'@context':
|
|
type: array
|
|
items:
|
|
type: string
|
|
format: uri
|
|
uniqueItems: true
|
|
contains:
|
|
const: 'https://schema.beckn.io/OnCatalogPublishAction/v2.0/context.jsonld'
|
|
minItems: 1
|
|
'@type':
|
|
type: array
|
|
items:
|
|
type: string
|
|
format: uri
|
|
uniqueItems: true
|
|
contains:
|
|
const: 'beckn:OnCatalogPublishAction'
|
|
minItems: 1
|
|
context:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Context'
|
|
- type: object
|
|
properties:
|
|
action:
|
|
const: 'on_catalog_publish'
|
|
|
|
message:
|
|
type: object
|
|
properties:
|
|
results:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/CatalogProcessingResult'
|
|
|
|
ConfirmAction:
|
|
$id: https://schema.beckn.io/ConfirmAction/v2.0
|
|
title: Confirm Action
|
|
description: |
|
|
Beckn /beckn/confirm message payload. Sent by a BAP to a BPP to confirm
|
|
a contract, finalising the transaction terms agreed during the
|
|
select-init negotiation cycle.
|
|
(Context wrapper stripped; only the message-content portion is inlined.)
|
|
oneOf:
|
|
- type: object
|
|
required: [order]
|
|
properties:
|
|
order:
|
|
type: object
|
|
- type: object
|
|
required: [contract]
|
|
properties:
|
|
contract:
|
|
$ref: '#/components/schemas/Contract'
|
|
|
|
DiscoverAction:
|
|
$id: https://schema.beckn.io/DiscoverAction/v2.0
|
|
title: Discover Action (External)
|
|
description: |
|
|
Beckn /beckn/discover message payload as published at schema.beckn.io.
|
|
Supports two forms: intent properties directly at the top level (flat),
|
|
or all intent properties nested inside an `intent` container object.
|
|
(Context wrapper stripped; only the message-content portion is inlined.)
|
|
oneOf:
|
|
- description: Flat form — Intent properties directly at top level (no intent container)
|
|
$ref: '#/components/schemas/Intent'
|
|
- description: Nested form — Intent properties inside an intent container object
|
|
type: object
|
|
required: [intent]
|
|
properties:
|
|
intent:
|
|
$ref: '#/components/schemas/Intent'
|
|
|
|
InitAction:
|
|
$id: https://schema.beckn.io/InitAction/v2.0
|
|
title: Init Action
|
|
description: |
|
|
Beckn /beckn/init message payload. Sent by a BAP to a BPP to initialise
|
|
a contract with consumer details (billing address, fulfillment preferences, etc.).
|
|
(Context wrapper stripped; only the message-content portion is inlined.)
|
|
oneOf:
|
|
- type: object
|
|
required: [order]
|
|
properties:
|
|
order:
|
|
type: object
|
|
- type: object
|
|
required: [contract]
|
|
properties:
|
|
contract:
|
|
$ref: '#/components/schemas/Contract'
|
|
|
|
|
|
OnCancelAction:
|
|
$id: https://schema.beckn.io/OnCancelAction/v2.0
|
|
title: On Cancel Action
|
|
description: |
|
|
Beckn /beckn/on_cancel message payload. Sent by a BPP to a BAP in
|
|
response to a /beckn/cancel call, returning the contract with status
|
|
set to CANCELLED and any applicable cancellation outcome.
|
|
(Context wrapper stripped; only the message-content portion is inlined.)
|
|
oneOf:
|
|
- type: object
|
|
required: [order]
|
|
properties:
|
|
order:
|
|
type: object
|
|
- type: object
|
|
required: [contract]
|
|
properties:
|
|
contract:
|
|
$ref: '#/components/schemas/Contract'
|
|
|
|
OnConfirmAction:
|
|
$id: https://schema.beckn.io/OnConfirmAction/v2.0
|
|
title: OnConfirmAction
|
|
description: |
|
|
Beckn /beckn/on_confirm message payload. Sent by a BPP to a BAP in
|
|
response to a /beckn/confirm call, returning the confirmed contract
|
|
with status set to CONFIRMED.
|
|
(Context wrapper stripped; only the message-content portion is inlined.)
|
|
oneOf:
|
|
- type: object
|
|
required: [order]
|
|
properties:
|
|
order:
|
|
type: object
|
|
- type: object
|
|
required: [contract]
|
|
properties:
|
|
contract:
|
|
$ref: '#/components/schemas/Contract'
|
|
|
|
OnDiscoverAction:
|
|
$id: https://schema.beckn.io/OnDiscoverAction/v2.0
|
|
description: The on_discover response payload containing matching catalogs.
|
|
type: object
|
|
required: [catalogs]
|
|
properties:
|
|
catalogs:
|
|
type: array
|
|
description: |
|
|
Array of catalogs matching the discovery request.
|
|
Note: Each catalog's `items` array carries `oneOf [Item, Resource]` entries:
|
|
- `Item` — legacy 2.0-rc1 catalog item (backward compatible)
|
|
- `Resource` — new cross-domain resource abstraction (generalized)
|
|
Both types share the common `id` + `descriptor` surface for display rendering.
|
|
See `#/components/schemas/Catalog/v2.0` for the full Catalog schema.
|
|
items:
|
|
$ref: '#/components/schemas/Catalog'
|
|
|
|
OnInitAction:
|
|
$id: https://schema.beckn.io/OnInitAction/v2.0
|
|
title: On Init Action
|
|
description: |
|
|
Beckn /beckn/on_init message payload. Sent by a BPP to a BAP in response
|
|
to a /beckn/init call, with the updated contract including payment terms
|
|
and billing confirmation.
|
|
(Context wrapper stripped; only the message-content portion is inlined.)
|
|
oneOf:
|
|
- type: object
|
|
required: [order]
|
|
properties:
|
|
order:
|
|
type: object
|
|
- type: object
|
|
required: [contract]
|
|
properties:
|
|
contract:
|
|
$ref: '#/components/schemas/Contract'
|
|
|
|
OnRateAction:
|
|
$id: https://schema.beckn.io/OnRateAction/v2.0
|
|
title: On Rate Action
|
|
description: |
|
|
Beckn /beckn/on_rate message payload. Sent by a BPP to a BAP in
|
|
response to a /beckn/rate call, optionally returning rating forms
|
|
to collect structured feedback from the consumer.
|
|
(Context wrapper stripped; only the message-content portion is inlined.)
|
|
type: object
|
|
additionalProperties: true
|
|
properties:
|
|
ratingForms:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/RatingForm'
|
|
required:
|
|
- ratingForms
|
|
|
|
# ── Support Messages ────────────────────────────────────────────
|
|
|
|
OnSelectAction:
|
|
$id: https://schema.beckn.io/OnSelectAction/v2.0
|
|
title: On Select Action
|
|
description: |
|
|
Beckn /beckn/on_select message payload. Sent by a BPP to a BAP in
|
|
response to a /beckn/select call, with updated contract terms.
|
|
(Context wrapper stripped; only the message-content portion is inlined.)
|
|
oneOf:
|
|
- type: object
|
|
- $ref: '#/components/schemas/Contract'
|
|
|
|
OnStatusAction:
|
|
$id: https://schema.beckn.io/OnStatusAction/v2.0
|
|
title: On Status Action
|
|
description: |
|
|
Beckn /beckn/on_status message payload. Sent by a BPP to a BAP in
|
|
response to a /beckn/status call (or as an unsolicited status push),
|
|
returning the current state of the contract.
|
|
(Context wrapper stripped; only the message-content portion is inlined.)
|
|
oneOf:
|
|
- type: object
|
|
required: [order]
|
|
properties:
|
|
order:
|
|
type: object
|
|
- type: object
|
|
required: [contract]
|
|
properties:
|
|
contract:
|
|
$ref: '#/components/schemas/Contract'
|
|
|
|
OnSupportAction:
|
|
$id: https://schema.beckn.io/OnSupportAction/v2.0
|
|
title: On Support Action
|
|
description: |
|
|
Beckn /beckn/on_support message payload. Sent by a BPP to a BAP in
|
|
response to a /beckn/support call, returning support contact details
|
|
and available channels.
|
|
(Context wrapper stripped; only the message-content portion is inlined.)
|
|
type: object
|
|
properties:
|
|
support:
|
|
$ref: '#/components/schemas/Support'
|
|
required:
|
|
- support
|
|
|
|
|
|
# ── Catalog Publishing Messages ─────────────────────────────────
|
|
|
|
OnTrackAction:
|
|
$id: https://schema.beckn.io/OnTrackAction/v2.0
|
|
title: On Track Action
|
|
description: |
|
|
Beckn /beckn/on_track message payload. Sent by a BPP to a BAP in
|
|
response to a /beckn/track call, returning a Tracking handle with
|
|
the URL and/or WebSocket endpoint for real-time fulfillment tracking.
|
|
(Context wrapper stripped; only the message-content portion is inlined.)
|
|
type: object
|
|
additionalProperties: true
|
|
properties:
|
|
tracking:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Tracking'
|
|
required:
|
|
- tracking
|
|
|
|
OnUpdateAction:
|
|
$id: https://schema.beckn.io/OnUpdateAction/v2.0
|
|
title: On Update Action
|
|
description: |
|
|
Beckn /beckn/on_update message payload. Sent by a BPP to a BAP in
|
|
response to a /beckn/update call (or as an unsolicited update push),
|
|
returning the updated contract state.
|
|
(Context wrapper stripped; only the message-content portion is inlined.)
|
|
oneOf:
|
|
- type: object
|
|
required: [order]
|
|
properties:
|
|
order:
|
|
type: object
|
|
- type: object
|
|
required: [contract]
|
|
properties:
|
|
contract:
|
|
$ref: '#/components/schemas/Contract'
|
|
|
|
|
|
RateAction:
|
|
$id: https://schema.beckn.io/RateAction/v2.0
|
|
title: RateAction
|
|
description: |
|
|
Beckn /beckn/rate message payload. Sent by a BAP to a BPP to submit
|
|
one or more rating inputs for entities in a completed contract
|
|
(order, fulfillment, item, provider, agent, support).
|
|
(Context wrapper stripped; only the message-content portion is inlined.)
|
|
oneOf:
|
|
- type: object
|
|
properties:
|
|
ratings:
|
|
type: array
|
|
items:
|
|
type: object
|
|
- type: object
|
|
additionalProperties: true
|
|
properties:
|
|
ratingInputs:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/RatingInput'
|
|
required:
|
|
- ratingInputs
|
|
|
|
|
|
SelectAction:
|
|
$id: 'https://schema.beckn.io/SelectAction/v2.0'
|
|
title: Select Action
|
|
description: |
|
|
Beckn /beckn/select message payload. Sent by a BAP to a BPP to select
|
|
items and offers from a catalog, initiating the negotiation cycle.
|
|
(Context wrapper stripped; only the message-content portion is inlined.)
|
|
oneOf:
|
|
- type: object
|
|
required: [order]
|
|
properties:
|
|
order:
|
|
type: object
|
|
- type: object
|
|
required: [contract]
|
|
properties:
|
|
contract:
|
|
$ref: '#/components/schemas/Contract'
|
|
|
|
StatusAction:
|
|
$id: https://schema.beckn.io/StatusAction/v2.0
|
|
title: Status Action
|
|
description: |
|
|
Beckn /beckn/status message payload. Sent by a BAP to a BPP to query
|
|
the current state of a contract/order by its identifier.
|
|
(Context wrapper stripped; only the message-content portion is inlined.)
|
|
oneOf:
|
|
- type: object
|
|
description: Query by order identifier (legacy)
|
|
required: [order]
|
|
properties:
|
|
order:
|
|
allOf:
|
|
- type: object
|
|
- required: ['beckn:id']
|
|
- type: object
|
|
description: Query by contract identifier
|
|
required: [contract]
|
|
properties:
|
|
contract:
|
|
type: object
|
|
required: [id]
|
|
properties:
|
|
id:
|
|
$ref: '#/components/schemas/Contract/properties/id'
|
|
|
|
SupportAction:
|
|
$id: https://schema.beckn.io/SupportAction/v2.0
|
|
title: Support Action
|
|
description: |
|
|
Beckn /beckn/support message payload. Sent by a BAP to a BPP to request
|
|
support contact information or to open a support ticket for an existing
|
|
order/contract.
|
|
(Context wrapper stripped; only the message-content portion is inlined.)
|
|
oneOf:
|
|
- type: object
|
|
- type: object
|
|
properties:
|
|
support:
|
|
$ref: '#/components/schemas/Support'
|
|
required:
|
|
- support
|
|
|
|
|
|
TrackAction:
|
|
oneOf:
|
|
- type: object
|
|
- type: object
|
|
title: Track Action
|
|
description: |
|
|
Beckn /beckn/track message payload. Sent by a BAP to a BPP to request
|
|
a real-time tracking handle for a fulfillment within an active contract.
|
|
(Context wrapper stripped; only the message-content portion is inlined.)
|
|
properties:
|
|
tracking:
|
|
type: object
|
|
properties:
|
|
contract:
|
|
type: object
|
|
properties:
|
|
id:
|
|
$ref: '#/components/schemas/Contract/properties/id'
|
|
trackingData:
|
|
type: object
|
|
description: Domain-specific extension attributes for this track action.
|
|
properties:
|
|
'@context':
|
|
type: array
|
|
items:
|
|
type: string
|
|
format: uri
|
|
uniqueItems: true
|
|
contains:
|
|
const: 'https://schema.beckn.io/TrackAction/v2.0/context.jsonld'
|
|
minItems: 1
|
|
'@type':
|
|
type: array
|
|
items:
|
|
type: string
|
|
format: uri
|
|
uniqueItems: true
|
|
contains:
|
|
const: 'beckn:TrackAction'
|
|
minItems: 1
|
|
trackingAttributes:
|
|
description: Domain-specific extension attributes for this Tracking.
|
|
allOf:
|
|
- $ref: '#/components/schemas/Attributes'
|
|
- required:
|
|
- '@context'
|
|
- '@type'
|
|
- properties:
|
|
'@context':
|
|
description: Domain-specific context in which this contract is being created
|
|
type: string
|
|
format: uri
|
|
examples:
|
|
- 'https://schema.beckn.io/LongPolling/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/WebhookPush/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/Streaming/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/WebPage/v2.0/context.jsonld'
|
|
'@type':
|
|
description: JSON-LD type corresponding to the context
|
|
type: string
|
|
examples:
|
|
- LongPolling
|
|
- WebhookPush
|
|
- Streaming
|
|
- WebPage
|
|
additionalProperties: true
|
|
required:
|
|
- contract
|
|
additionalProperties: false
|
|
|
|
|
|
# ── Status Message ──────────────────────────────────────────────
|
|
|
|
UpdateAction:
|
|
$id: https://schema.beckn.io/UpdateAction/v2.0
|
|
title: Update Action
|
|
description: |
|
|
Beckn /beckn/update message payload. Sent by a BAP to a BPP to request
|
|
changes to an active contract (e.g., update fulfillment address, add items,
|
|
change quantities). The context.try flag must be true during negotiation.
|
|
(Context wrapper stripped; only the message-content portion is inlined.)
|
|
oneOf:
|
|
- type: object
|
|
required: [order]
|
|
properties:
|
|
order:
|
|
type: object
|
|
- type: object
|
|
properties:
|
|
contract:
|
|
$ref: '#/components/schemas/Contract'
|
|
|
|
# ─── Responses ────────────────────────────────────────────────────
|
|
|
|
# ─────────────────────────────────────────────────────────────────────
|
|
# CORE DATA SCHEMAS — Reusable types, domain objects, and infrastructure
|
|
# ─────────────────────────────────────────────────────────────────────
|
|
ActionTrigger:
|
|
description: Describes a trigger that initiates an action, like triggering a settlement on fulfillment completion.
|
|
type: object
|
|
properties:
|
|
'@context':
|
|
type: string
|
|
format: uri
|
|
'@type':
|
|
type: string
|
|
descriptor:
|
|
$ref: '#/components/schemas/Descriptor'
|
|
|
|
AddOn:
|
|
type: object
|
|
description: Add-on to a catalog resource
|
|
properties:
|
|
id:
|
|
type: string
|
|
descriptor:
|
|
$ref: '#/components/schemas/Descriptor'
|
|
addOnAttributes:
|
|
description: >
|
|
Domain-specific extension attributes for this add-on.
|
|
allOf:
|
|
- $ref: '#/components/schemas/Attributes'
|
|
- required:
|
|
- '@context'
|
|
- '@type'
|
|
- properties:
|
|
'@context':
|
|
description: Domain-specific context in which this add-on exists
|
|
type: string
|
|
format: uri
|
|
examples:
|
|
- 'https://schema.beckn.io/FnbAddOn/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/GroceryAddOn/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/RideAddOn/v2.0/context.jsonld'
|
|
'@type':
|
|
description: JSON-LD type corresponding to the context
|
|
type: string
|
|
examples:
|
|
- FnbAddOn
|
|
- GroceryAddOn
|
|
- RideAddOn
|
|
Address:
|
|
$id: https://schema.beckn.io/Address/v2.0
|
|
description: '**Postal address** aligned with schema.org `PostalAddress`. Use for human-readable addresses.
|
|
Geometry lives in `Location.geo` as GeoJSON.'
|
|
title: Address
|
|
type: object
|
|
properties:
|
|
addressCountry:
|
|
description: Country name or ISO-3166-1 alpha-2 code.
|
|
type: string
|
|
example: IN
|
|
addressLocality:
|
|
description: City/locality.
|
|
type: string
|
|
example: Bengaluru
|
|
addressRegion:
|
|
description: State/region/province.
|
|
type: string
|
|
example: Karnataka
|
|
extendedAddress:
|
|
description: Address extension (apt/suite/floor, C/O).
|
|
type: string
|
|
example: Apt 4B
|
|
postalCode:
|
|
description: Postal/ZIP code.
|
|
type: string
|
|
example: '560001'
|
|
streetAddress:
|
|
description: Street address (building name/number and street).
|
|
type: string
|
|
example: 123 Tech Street
|
|
additionalProperties: false
|
|
x-tags:
|
|
- common
|
|
|
|
AsyncError:
|
|
title: Asynchronous Error
|
|
description: |
|
|
Error returned asynchronously during a callback. Wraps the base `Error` schema with JSON-LD type annotations to allow linked-data processing.
|
|
allOf:
|
|
- $ref: '#/components/schemas/Error'
|
|
- type: object
|
|
properties:
|
|
'@context':
|
|
type: string
|
|
default: '#/components/schemas/'
|
|
'@type':
|
|
type: string
|
|
default: AsyncError
|
|
additionalProperties: true
|
|
|
|
Attributes:
|
|
$id: 'https://schema.beckn.io/Attributes/v2.0'
|
|
description: JSON-LD aware container for domain-specific attributes of an Item. MUST include @context
|
|
(URI) and @type (compact or full IRI). Any additional properties are allowed and interpreted per the
|
|
provided JSON-LD context.
|
|
title: Attributes
|
|
type: object
|
|
properties:
|
|
'@context':
|
|
description: Use case specific JSON-LD context URI
|
|
type: string
|
|
format: uri
|
|
'@type':
|
|
description: JSON-LD type defined within the context
|
|
type: string
|
|
required:
|
|
- '@context'
|
|
- '@type'
|
|
additionalProperties: true
|
|
x-tags:
|
|
- common
|
|
|
|
Catalog:
|
|
$id: https://schema.beckn.io/Catalog/v2.1
|
|
$schema: "https://json-schema.org/draft/2020-12/schema"
|
|
description: Catalog schema for Beckn Protocol v2.0.1 — oneOf legacy (v2.0) or new (v2.1) catalog format
|
|
title: Catalog
|
|
x-tags: [common]
|
|
type: object
|
|
properties:
|
|
bppId:
|
|
description: BPP (Beckn Protocol Provider) identifier that publishes this catalog
|
|
type: string
|
|
example: bpp.example.com
|
|
bppUri:
|
|
description: BPP (Beckn Protocol Provider) URI endpoint
|
|
type: string
|
|
format: uri
|
|
example: "https://bpp.example.com"
|
|
descriptor:
|
|
description: Human / Agent-readable description of this catalog
|
|
allOf:
|
|
- $ref: "#/components/schemas/Descriptor"
|
|
id:
|
|
description: Unique identifier for the catalog
|
|
type: string
|
|
example: catalog-electronics-001
|
|
isActive:
|
|
description: Whether the catalog is active
|
|
type: boolean
|
|
default: true
|
|
offers:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Offer"
|
|
resources:
|
|
description: Array of generalized Resource entities in this catalog (new model)
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Resource'
|
|
provider:
|
|
description: The provider of the catalog
|
|
allOf:
|
|
- $ref: "#/components/schemas/Provider"
|
|
visibleTo:
|
|
type: array
|
|
description: >
|
|
Optional visibility constraint indicating which network participants
|
|
(by participantId / networkId / role) are allowed to discover or
|
|
transact on this catalog.
|
|
|
|
If omitted, the catalog is assumed to be visible to all participants
|
|
in the addressed network(s).
|
|
items:
|
|
type: object
|
|
required: [type, id]
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [NETWORK, PARTICIPANT, ROLE]
|
|
description: Scope of visibility constraint.
|
|
id:
|
|
type: string
|
|
description: Identifier of the network, participant, or role.
|
|
validity:
|
|
description: The time period during which this catalog is valid
|
|
$ref: "#/components/schemas/TimePeriod"
|
|
required:
|
|
- id
|
|
- descriptor
|
|
additionalProperties: false
|
|
|
|
CatalogOnPublishMessage:
|
|
$id: 'https:schema.beckn.io/CatalogOnPublishMessage/v2.0'
|
|
description: Catalog publish processing results from CDS to BPP.
|
|
type: object
|
|
required: [results]
|
|
properties:
|
|
results:
|
|
type: array
|
|
description: Per-catalog processing results
|
|
items:
|
|
$ref: '#/components/schemas/CatalogProcessingResult'
|
|
|
|
CatalogProcessingResult:
|
|
$id: 'https://schema.beckn.io/CatalogProcessingResult/v2.0'
|
|
description: Processing result for a single catalog submission.
|
|
type: object
|
|
required: [catalogId, status]
|
|
properties:
|
|
catalogId:
|
|
type: string
|
|
description: Identifier of the submitted catalog
|
|
status:
|
|
description: |
|
|
Processing outcome. Using oneOf [string, object] to allow domain-specific
|
|
status objects (e.g. beckn:CatalogAccepted) alongside standard string codes.
|
|
oneOf:
|
|
- type: string
|
|
enum: [ACCEPTED, REJECTED, PARTIAL]
|
|
description: |
|
|
Standard processing status:
|
|
- ACCEPTED — catalog indexed successfully
|
|
- REJECTED — catalog rejected entirely (see errors)
|
|
- PARTIAL — some items accepted, some rejected (see errors)
|
|
- type: object
|
|
properties:
|
|
'@context':
|
|
type: string
|
|
format: uri
|
|
const: '#/components/schemas/'
|
|
'@type':
|
|
type: string
|
|
pattern: '^beckn:[A-Za-z0-9._~-]+$'
|
|
additionalProperties: true
|
|
errors:
|
|
type: array
|
|
description: Per-item or per-catalog errors (present when REJECTED or PARTIAL)
|
|
items:
|
|
$ref: '#/components/schemas/Error'
|
|
stats:
|
|
type: object
|
|
description: Optional statistics about the processed catalog
|
|
properties:
|
|
itemCount:
|
|
type: integer
|
|
description: Number of items accepted
|
|
providerCount:
|
|
type: integer
|
|
description: Number of providers in the catalog
|
|
categoryCount:
|
|
type: integer
|
|
description: Number of distinct categories
|
|
|
|
Consideration:
|
|
$id: https://schema.beckn.io/Consideration/v2.0
|
|
type: object
|
|
description: >
|
|
Generalized representation of value exchanged under a Contract.
|
|
|
|
Consideration is domain-neutral and may represent:
|
|
- Monetary value
|
|
- Credits / tokens
|
|
- Asset transfer
|
|
- Service exchange
|
|
- Compliance artifact
|
|
required: ["@context", "@type", "id", "status"]
|
|
properties:
|
|
"@context":
|
|
type: string
|
|
format: uri
|
|
description: JSON-LD context URI for the core Resource schema
|
|
"@type":
|
|
oneOf:
|
|
- type: string
|
|
description: Type of the core Resource
|
|
enum: ["beckn:Consideration", "beckn:MonetaryConsideration", "beckn:TokenConsideration", "beckn:CreditConsideration", "beckn:AssetConsideration", "beckn:ServiceConsideration"]
|
|
- type: string
|
|
id:
|
|
description: Identifier of this consideration
|
|
type: string
|
|
status:
|
|
description: The status of this consideration
|
|
$ref: '#/components/schemas/Descriptor'
|
|
considerationAttributes:
|
|
description: >
|
|
Domain-specific attributes of this consideration. For monetary considerations,
|
|
use the PriceSpecification schema to capture total value with breakup.
|
|
For other consideration types, use a generic Attributes bag.
|
|
$ref: '#/components/schemas/Attributes'
|
|
|
|
Context:
|
|
$id: "#/components/schemas/Context"
|
|
description: >-
|
|
Every API call in Beckn protocol has a context. It contains addressing information like the bap/bpp identifiers and API base urls, the protocol version implemented by the sender, the method being called, 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 specify the validity of the request, and a key to encrypt information if necessary.
|
|
title: Context
|
|
x-tags: [common]
|
|
type: object
|
|
properties:
|
|
action:
|
|
description: The Beckn endpoint being called. Must conform to BecknEndpoint format.
|
|
type: string
|
|
bapId:
|
|
description: A globally unique identifier of the BAP. Typically the fully qualified domain name (FQDN) of the BAP.
|
|
type: string
|
|
bapUri:
|
|
description: API URL of the BAP for accepting callbacks from BPPs.
|
|
type: string
|
|
format: uri
|
|
bppId:
|
|
description: A globally unique identifier of the BPP. Typically the fully qualified domain name (FQDN) of the BPP.
|
|
type: string
|
|
bppUri:
|
|
description: API URL of the BPP for accepting calls from BAPs.
|
|
type: string
|
|
format: uri
|
|
messageId:
|
|
description: >-
|
|
A unique value which persists during a request/callback cycle. BAPs use
|
|
this value to match an incoming callback from a BPP to an earlier call.
|
|
Generate a fresh message_id for every new interaction.
|
|
type: string
|
|
format: uuid
|
|
networkId:
|
|
description: A unique identifier representing a group of platforms. By default, the URL of the network registry on the Beckn network.
|
|
type: string
|
|
timestamp:
|
|
description: Time of request generation in RFC3339 format.
|
|
type: string
|
|
format: date-time
|
|
transactionId:
|
|
description: >-
|
|
A unique value which persists across all API calls from discover through
|
|
confirm. Used to indicate an active user session across multiple requests.
|
|
type: string
|
|
format: uuid
|
|
try:
|
|
description: A flag to indicate that this request is intended to try an operation in sandbox mode
|
|
type: boolean
|
|
default: false
|
|
ttl:
|
|
description: The duration in ISO8601 format after timestamp for which this message holds valid.
|
|
type: string
|
|
version:
|
|
description: Version of Beckn protocol being used by the sender.
|
|
type: string
|
|
default: 2.0.0
|
|
required:
|
|
- action
|
|
- bapId
|
|
- bapUri
|
|
- messageId
|
|
- timestamp
|
|
- transactionId
|
|
- version
|
|
additionalProperties: false
|
|
|
|
Contract:
|
|
$id: https://schema.beckn.io/Contract/v2.1
|
|
type: object
|
|
description: >
|
|
This is a JSON-LD compliant, linked-data schema that specifies a generic multi-party, digitally signed Contract between a set of participants. based on the vocabulary defined in the @context. By default, it is the most generic form of contract i.e beckn:Contract. However, based on the mapping being used in @context, it could take values like retail:Order, mobility:Reservation, healthcare:Appointment, and so on, which will be defined as sub-classes of beckn:Contract.
|
|
Alternate description A digitally agreed commitment between two or more participants
|
|
governing the exchange of economic or non-economic value.
|
|
|
|
Contract is the canonical contract object in the generalized
|
|
Beckn v2.1 protocol. It replaces the commerce-specific Order construct
|
|
while preserving backward compatibility at the API layer.
|
|
|
|
A Contract binds:
|
|
- Commitments (what is agreed)
|
|
- Consideration (value promised)
|
|
- Performance (how execution occurs)
|
|
- Settlements (how consideration is discharged)
|
|
|
|
The model is domain-neutral and supports commerce, hiring,
|
|
energy markets, carbon exchanges, data access, mobility,
|
|
subscriptions, and other use cases.
|
|
title: Contract
|
|
properties:
|
|
'@context':
|
|
description: A URL to the reference vocabulary where this schema has been defined. If missing, this field defaults to `https://schema.beckn.io/`. It allows applications to fetch the mapping between the simple JSON keys of this class and absolute Beckn IRIs (Internationalized Resource Identifiers), allowing conversion of standard Beckn JSON payload into linked data.
|
|
type: string
|
|
format: uri
|
|
const: https://schema.beckn.io/Contract/v2.0
|
|
'@type':
|
|
description: A Beckn IRI on the vocabulary defined in the @context. Must start with "beckn:" followed by URL-safe identifier characters.
|
|
type: string
|
|
pattern: ^beckn:[A-Za-z0-9._~-]+$
|
|
default: beckn:Contract
|
|
id:
|
|
description: A UUID string generated at the BPP endpoint at any stage before the confirmation of the order i.e before `/on_confirm` callback. This value is intended typically for indexing or filtering. While the chances of a UUID collision are rare, it is recommended to use a combination of `bppId`, `providerId` and `id` to allow for global uniqueness.
|
|
type: string
|
|
format: uuid
|
|
descriptor:
|
|
description: Describes the nature of the contract in human / agent readable terms
|
|
$ref: '#/components/schemas/Descriptor'
|
|
commitments:
|
|
type: array
|
|
description: >
|
|
Structured commitments governed by this contract.
|
|
minItems: 1
|
|
items:
|
|
$ref: '#/components/schemas/Commitment'
|
|
consideration:
|
|
type: array
|
|
description: Value agreed to be exchanged under this contract.
|
|
items:
|
|
$ref: '#/components/schemas/Consideration'
|
|
participants:
|
|
description: |
|
|
The participants involved in the contract. Contracts are not always between two individuals.
|
|
|
|
Several entities may play a specific role in the creation, fulfillment, and post-fulfillment of
|
|
the contract.
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Participant'
|
|
performance:
|
|
type: array
|
|
description: >
|
|
Execution units of the contract.
|
|
|
|
Previously defined as `fulfillments`, performance is the generalized the legacy Fulfillment abstraction.
|
|
Each Performance instance represents a structured execution
|
|
plan or delivery mechanism, including:
|
|
|
|
- Physical delivery
|
|
- Service provisioning
|
|
- API access
|
|
- Subscription activation
|
|
- Carbon credit transfer
|
|
- Capacity allocation
|
|
- Workforce onboarding
|
|
|
|
Tracking and Support interactions may be linked to
|
|
individual Performance units.
|
|
items:
|
|
$ref: '#/components/schemas/Performance'
|
|
entitlements:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Entitlement'
|
|
settlements:
|
|
type: array
|
|
description: >
|
|
Records representing discharge of agreed consideration.
|
|
items:
|
|
$ref: '#/components/schemas/Settlement'
|
|
terms:
|
|
type: array
|
|
description: >
|
|
Records representing discharge of agreed consideration.
|
|
items:
|
|
$ref: '#/components/schemas/Attributes'
|
|
status:
|
|
description: The current state of the contract expressed as a Descriptor whose code MUST be one of the standard contract state values.
|
|
allOf:
|
|
- $ref: '#/components/schemas/Descriptor'
|
|
- type: object
|
|
properties:
|
|
code:
|
|
enum: [DRAFT, ACTIVE, CANCELLED, COMPLETE]
|
|
contractAttributes:
|
|
description: >
|
|
Domain-specific extension attributes for this contract.
|
|
Use beckn:LogisticsContract for hyperlocal physical delivery. Use the generic Attributes schema for
|
|
other fulfillment types where no well-known domain schema exists.
|
|
allOf:
|
|
- $ref: '#/components/schemas/Attributes'
|
|
- required:
|
|
- '@context'
|
|
- '@type'
|
|
- properties:
|
|
'@context':
|
|
description: Domain-specific context in which this contract is being created
|
|
type: string
|
|
format: uri
|
|
examples:
|
|
- 'https://schema.beckn.io/GroceryOrder/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/FnBOrder/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/ShippingOrder/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/MobilityBooking/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/BusTicketBooking/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/P2PEnergyTrade/v1.1/context.jsonld'
|
|
'@type':
|
|
description: JSON-LD type corresponding to the context
|
|
type: string
|
|
examples:
|
|
- GroceryOrder
|
|
- FnBOrder
|
|
- ShippingOrder
|
|
- MobilityBooking
|
|
- BusTicketBooking
|
|
- P2PEnergyTrade
|
|
|
|
additionalProperties: false
|
|
x-tags:
|
|
- common
|
|
required:
|
|
- commitments
|
|
|
|
Commitment:
|
|
type: object
|
|
required:
|
|
- status
|
|
- resources
|
|
- offer
|
|
properties:
|
|
"@context":
|
|
type: string
|
|
format: uri
|
|
description: JSON-LD context URI for the core Resource schema
|
|
"@type":
|
|
type: string
|
|
description: Type of the core Resource
|
|
enum: ["beckn:Commitment"]
|
|
id:
|
|
type: string
|
|
status:
|
|
type: object
|
|
properties:
|
|
descriptor:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Descriptor'
|
|
- properties:
|
|
code:
|
|
enum:
|
|
- DRAFT
|
|
- ACTIVE
|
|
- CLOSED
|
|
resources:
|
|
type: array
|
|
items:
|
|
required:
|
|
- id
|
|
- quantity
|
|
$ref: '#/components/schemas/Resource'
|
|
offer:
|
|
required:
|
|
- id
|
|
- resourceIds
|
|
$ref: '#/components/schemas/Offer'
|
|
commitmentAttributes:
|
|
description: >
|
|
Domain-specific extension attributes for this commitment.
|
|
allOf:
|
|
- $ref: '#/components/schemas/Attributes'
|
|
- required:
|
|
- '@context'
|
|
- '@type'
|
|
properties:
|
|
'@context':
|
|
description: Domain-specific attributes for this commitment
|
|
type: string
|
|
format: uri
|
|
examples:
|
|
- 'https://schema.beckn.io/ShoppingCart/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/ShippingManifest/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/TravelItinerary/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/BillOfMaterials/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/DiagnosticTests/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/TodoList/v2.0/context.jsonld'
|
|
'@type':
|
|
description: JSON-LD type corresponding to the context
|
|
type: string
|
|
examples:
|
|
- ShoppingCart
|
|
- ShippingManifest
|
|
- TravelItinerary
|
|
- BillOfMaterials
|
|
- DiagnosticTests
|
|
- TodoList
|
|
|
|
CounterSignature:
|
|
title: Beckn HTTP Counter-Signature
|
|
description: |
|
|
A signed receipt transmitted in the synchronous `Ack` response body, proving that the
|
|
receiver authenticated, received, and processed the inbound request.
|
|
|
|
`CounterSignature` shares the same wire format as `Signature` but differs:
|
|
- **Signer**: the response receiver (not the request sender)
|
|
- **Location**: transmitted in the `Ack` response body (not in the `Authorization` header)
|
|
- **`digest`**: covers the Ack response body (not the inbound request body)
|
|
- **`(request-digest)`** and **`(message-id)`** MUST be included in the signing string
|
|
|
|
Signing string format:
|
|
```
|
|
(created): {unixTimestamp}
|
|
(expires): {unixTimestamp}
|
|
digest: BLAKE-512={base64DigestOfAckBody}
|
|
(request-digest): BLAKE-512={base64DigestOfInboundRequestBody}
|
|
(message-id): {messageId}
|
|
```
|
|
allOf:
|
|
- $ref: '#/components/schemas/Signature'
|
|
|
|
Descriptor:
|
|
$id: "#/components/schemas/Descriptor"
|
|
$schema: "https://json-schema.org/draft/2020-12/schema"
|
|
description: Schema definition for Descriptor in the Beckn Protocol v2.0.1
|
|
title: Descriptor
|
|
x-tags: [common]
|
|
type: object
|
|
properties:
|
|
'@context':
|
|
description: Use case specific JSON-LD context. This can change from use case to use case, even within a domain.
|
|
type: string
|
|
format: uri
|
|
default: "https://schema.beckn.io/"
|
|
'@type':
|
|
description: Type of the descriptor. The type can be overriden with a context-specific type
|
|
type: string
|
|
default: beckn:Descriptor
|
|
code:
|
|
description: A machine-readable code identifying the state or type of the entity being described. The valid values for this field are defined by the context in which the Descriptor is used (e.g. DRAFT, ACTIVE, CANCELLED, COMPLETE for a Contract status).
|
|
type: string
|
|
longDesc:
|
|
description: Detailed description of the item
|
|
type: string
|
|
example: Powerful gaming laptop with NVIDIA RTX graphics, fast SSD storage, and high-refresh display
|
|
shortDesc:
|
|
description: Short description of the item
|
|
type: string
|
|
example: High-performance gaming laptop with RTX graphics
|
|
name:
|
|
description: Name of the entity being described
|
|
type: string
|
|
example: Premium Gaming Laptop Pro
|
|
thumbnailImage:
|
|
description: Name of the entity being described
|
|
type: string
|
|
format: uri
|
|
docs:
|
|
description: Links to downloadable documents
|
|
type: array
|
|
items:
|
|
type: object
|
|
mediaFile:
|
|
description: Links to multimedia files and images
|
|
type: array
|
|
items:
|
|
type: object
|
|
required:
|
|
- '@type'
|
|
additionalProperties: false
|
|
|
|
Entitlement:
|
|
$id: https://schema.beckn.io/Entitlement/v2.0
|
|
description: A contractually granted, policy-governed right that allows a specific party to access, use, or claim a defined economic resource within stated scope and validity constraints. It represents the enforceable permission created by an order, independent of the credential used to exercise it.
|
|
title: Entitlement
|
|
type: object
|
|
properties:
|
|
'@context':
|
|
description: CPD
|
|
type: string
|
|
format: uri
|
|
default: https://schema.beckn.io/
|
|
'@type':
|
|
description: The domain-specific type of entitlement that allows domains to extend this schema
|
|
type: string
|
|
default: beckn:Entitlement
|
|
id:
|
|
description: A unique identifier for this entitlement within the entitlement provider's namespace
|
|
type: string
|
|
resource:
|
|
description: The resource being availed or accessed against this entitlement
|
|
$ref: '#/components/schemas/Resource/properties/id'
|
|
descriptor:
|
|
description: Human-readable information regarding the entitlement like QR-code images, attached documents containing terms and conditions, video or audio files instructing the user on how to use the entitlement
|
|
$ref: '#/components/schemas/Descriptor'
|
|
credentials:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Descriptor'
|
|
additionalProperties: true
|
|
required:
|
|
- '@context'
|
|
- '@type'
|
|
- id
|
|
- descriptor
|
|
x-tags:
|
|
- common
|
|
|
|
Error:
|
|
$id: '#/components/schemas/Error/v2.0'
|
|
title: Error
|
|
description: |
|
|
Base error container returned in NACK responses and async error callbacks.
|
|
Domain-specific error codes SHOULD follow the Beckn error code registry
|
|
(see docs/11_Error_Codes.md). Custom error objects may be expressed as
|
|
`oneOf [string, object]` payloads via the `errorDetails` field.
|
|
oneOf:
|
|
- description: Newest version of the error object properties.
|
|
type: object
|
|
properties:
|
|
errorCode:
|
|
type: string
|
|
description: Machine-readable error code per the Beckn error registry.
|
|
errorMessage:
|
|
type: string
|
|
description: Human-readable error description for display or logging.
|
|
errorDetails:
|
|
description: |
|
|
Optional domain-specific error details. Using oneOf to allow both simple
|
|
string details and structured JSON-LD error objects from domain packs.
|
|
oneOf:
|
|
- type: string
|
|
- type: object
|
|
additionalProperties: true
|
|
- description: Error response object from the previous version
|
|
type: object
|
|
required: [code, message]
|
|
properties:
|
|
code:
|
|
type: string
|
|
message:
|
|
type: string
|
|
details:
|
|
type: object
|
|
Participant:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
descriptor:
|
|
$ref: '#/components/schemas/Descriptor'
|
|
participantAttributes:
|
|
description: >
|
|
Domain-specific extension attributes for this contract.
|
|
Use beckn:LogisticsContract for hyperlocal physical delivery. Use the generic Attributes schema for
|
|
other fulfillment types where no well-known domain schema exists.
|
|
allOf:
|
|
- $ref: '#/components/schemas/Attributes'
|
|
- required:
|
|
- '@context'
|
|
- '@type'
|
|
properties:
|
|
'@context':
|
|
description: Domain-specific entity which is is participating in this transaction
|
|
type: string
|
|
format: uri
|
|
examples:
|
|
- 'https://schema.beckn.io/Consumer/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/Provider/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/FulfillmentAgent/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/NetworkParticipant/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/EscrowAgent/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/Guarantor/v2.0/context.jsonld'
|
|
'@type':
|
|
description: JSON-LD type corresponding to the context
|
|
type: string
|
|
examples:
|
|
- Consumer
|
|
- Provider
|
|
- FulfillmentAgent
|
|
- NetworkParticipant
|
|
- EscrowAgent
|
|
- Guarantor
|
|
|
|
GeoJSONGeometry:
|
|
$id: 'https://schema.beckn.io/GeoJSONGeometry/v2.0'
|
|
description: "**GeoJSON geometry** per RFC 7946. Coordinates are in **EPSG:4326 (WGS-84)** and MUST follow\
|
|
\ **[longitude, latitude, (altitude?)]** order.\nSupported types: - Point, LineString, Polygon - MultiPoint,\
|
|
\ MultiLineString, MultiPolygon - GeometryCollection (uses `geometries` instead of `coordinates`)\n\
|
|
Notes: - For rectangles, use a Polygon with a single linear ring where the first\n and last positions\
|
|
\ are identical.\n- Circles are **not native** to GeoJSON. For circular searches, use\n `SpatialConstraint`\
|
|
\ with `op: s_dwithin` and a Point + `distanceMeters`,\n or approximate the circle as a Polygon.\n\
|
|
- Optional `bbox` is `[west, south, east, north]` in degrees.\n"
|
|
title: GeoJSONGeometry
|
|
type: object
|
|
properties:
|
|
bbox:
|
|
description: Optional bounding box `[west, south, east, north]` in degrees.
|
|
type: array
|
|
minItems: 4
|
|
maxItems: 4
|
|
coordinates:
|
|
description: Coordinates per RFC 7946 for all types **except** GeometryCollection. Order is **[lon,
|
|
lat, (alt)]**. For Polygons, this is an array of linear rings; each ring is an array of positions.
|
|
type: array
|
|
geometries:
|
|
description: Member geometries when `type` is **GeometryCollection**.
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/GeoJSONGeometry'
|
|
type:
|
|
type: string
|
|
enum:
|
|
- Point
|
|
- LineString
|
|
- Polygon
|
|
- MultiPoint
|
|
- MultiLineString
|
|
- MultiPolygon
|
|
- GeometryCollection
|
|
required:
|
|
- type
|
|
additionalProperties: true
|
|
x-tags:
|
|
- common
|
|
|
|
Performance:
|
|
$id: "https://schema.beckn.io/Performance/v2.2"
|
|
description: |
|
|
Generalized execution/performance unit. This is where downstream objects bind:
|
|
- Fulfillment-like details (where/when/how)
|
|
- Tracking handles
|
|
- Support touchpoints
|
|
- Status updates
|
|
|
|
A minimal envelope that carries identity, status, and a performanceAttributes
|
|
bag that holds the concrete domain-specific delivery schema.
|
|
|
|
Domain specification authors can attach rich context and types via `performanceAttributes`.
|
|
|
|
For example, Hyperlocal delivery details (pickup/delivery locations, items shipped, agent, etc.)
|
|
are placed inside performanceAttributes using a well-known domain schema such as
|
|
HyperlocalDelivery. Use the generic Attributes schema when no well-known
|
|
domain schema exists.
|
|
title: Fulfillment
|
|
x-tags: [common, fulfillment]
|
|
type: object
|
|
properties:
|
|
'@context':
|
|
description: Domain-specific context in which this fulfillment is taking place
|
|
type: string
|
|
format: uri
|
|
const: 'https://schema.beckn.io/Performance/v2.1/context.jsonld'
|
|
'@type':
|
|
description: JSON-LD type.
|
|
type: string
|
|
default: 'Fulfillment'
|
|
id:
|
|
type: string
|
|
description: Unique identifier for this fulfillment record.
|
|
x-jsonld:
|
|
'@id': 'beckn:id'
|
|
status:
|
|
$ref: '#/components/schemas/Descriptor'
|
|
description: >
|
|
Current status of this fulfillment, expressed as a Descriptor.
|
|
Use Descriptor.code for machine-readable status values.
|
|
x-jsonld:
|
|
'@id': 'beckn:status'
|
|
commitmentIds:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Commitment/properties/id'
|
|
schedule:
|
|
$ref: '#/components/schemas/Schedule'
|
|
performanceAttributes:
|
|
description: >
|
|
Domain-specific extension attributes for this fulfillment.
|
|
Use beckn:HyperlocalDelivery (aligned with schema:ParcelDelivery) for
|
|
hyperlocal physical delivery. Use the generic Attributes schema for
|
|
other fulfillment types where no well-known domain schema exists.
|
|
allOf:
|
|
- $ref: '#/components/schemas/Attributes'
|
|
- properties:
|
|
'@context':
|
|
description: Domain-specific context in which this fulfillment is taking place
|
|
type: string
|
|
format: uri
|
|
examples:
|
|
- 'https://schema.beckn.io/HyperlocalDelivery/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/OnDemandRide/v2.0/context.jsonld'
|
|
- 'https://schema.beckn.io/P2PEnergyTransfer/v1.1/context.jsonld'
|
|
default: 'https://schema.beckn.io/Fulfillment/v2.1/context.jsonld'
|
|
'@type':
|
|
description: JSON-LD type.
|
|
type: string
|
|
examples:
|
|
- 'HyperlocalDelivery'
|
|
- 'OnDemandRide'
|
|
- 'P2PEnergyTransfer'
|
|
- 'Fulfillment'
|
|
required:
|
|
- '@context'
|
|
- '@type'
|
|
additionalProperties: false
|
|
|
|
InReplyTo:
|
|
$id: 'https://schema.beckn.io/InReplyTo/v2.0'
|
|
title: In-Reply-To Reference
|
|
description: |
|
|
A cryptographic binding that ties an asynchronous `on_<action>` callback to the
|
|
specific inbound request that triggered it. Establishes bilateral non-repudiation
|
|
for the asynchronous leg of a Beckn interaction.
|
|
|
|
Use `lineage` (on `Context`) for cross-transaction causality.
|
|
|
|
Verification steps:
|
|
1. Recompute BLAKE2b-512 digest of the original request body; compare to `digest`.
|
|
2. Confirm `messageId` matches the `messageId` from the original request `Context`.
|
|
type: object
|
|
required: [messageId, digest]
|
|
properties:
|
|
messageId:
|
|
type: string
|
|
format: uuid
|
|
description: The `messageId` of the parent request from its `Context`.
|
|
digest:
|
|
type: string
|
|
pattern: '^BLAKE-512=[A-Za-z0-9+/]+=*$'
|
|
description: |
|
|
BLAKE2b-512 hash of the parent request body, Base64-encoded with algorithm prefix.
|
|
Format: `BLAKE-512={base64EncodedHash}`
|
|
|
|
Intent:
|
|
$id: https://schema.beckn.io/Intent/v2.0
|
|
description: A declaration of an intent to transact
|
|
title: Intent
|
|
x-tags: [common]
|
|
type: object
|
|
properties:
|
|
textSearch:
|
|
description: Free text search query for items
|
|
type: string
|
|
example: gaming laptop premium tech
|
|
filters:
|
|
description: Filter criteria for items
|
|
type: object
|
|
properties:
|
|
type:
|
|
description: Type of filter expression
|
|
type: string
|
|
enum:
|
|
- jsonpath
|
|
default: jsonpath
|
|
expression:
|
|
description: Filter expression based on the specified type
|
|
type: string
|
|
example: $[?(@.rating.value >= 4.0 && @.electronic.brand.name == 'Premium Tech')]
|
|
required:
|
|
- type
|
|
- expression
|
|
spatial:
|
|
description: Optional array of spatial constraints (CQL2-JSON semantics).
|
|
type: array
|
|
items:
|
|
type: object
|
|
media_search:
|
|
$ref: "#/components/schemas/MediaSearch"
|
|
anyOf:
|
|
- required:
|
|
- textSearch
|
|
- required:
|
|
- filters
|
|
- required:
|
|
- spatial
|
|
- required:
|
|
- filters
|
|
- spatial
|
|
additionalProperties: false
|
|
|
|
|
|
Location:
|
|
description: |
|
|
A place represented by GeoJSON geometry and optional address.
|
|
Source: main/schema/core/v2/attributes.yaml#Location
|
|
type: object
|
|
required: [geo]
|
|
additionalProperties: false
|
|
properties:
|
|
"@type":
|
|
type: string
|
|
enum: ["beckn:Location"]
|
|
geo:
|
|
$ref: '#/components/schemas/GeoJSONGeometry'
|
|
address:
|
|
oneOf:
|
|
- type: string
|
|
- $ref: '#/components/schemas/Address'
|
|
|
|
MediaInput:
|
|
$id: https://schema.beckn.io/MediaInput/v2.0
|
|
type: object
|
|
required: [type, url]
|
|
properties:
|
|
id: { type: string }
|
|
type: { type: string, enum: [image, audio, video] }
|
|
url: { type: string, format: uri }
|
|
contentType: { type: string }
|
|
textHint: { type: string }
|
|
language: { type: string }
|
|
startMs: { type: integer }
|
|
endMs: { type: integer }
|
|
additionalProperties: false
|
|
|
|
MediaSearch:
|
|
$id: https://schema.beckn.io/MediaSearch/v2.0
|
|
type: object
|
|
properties:
|
|
media:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/MediaInput'
|
|
options:
|
|
$ref: '#/components/schemas/MediaSearchOptions'
|
|
additionalProperties: false
|
|
|
|
MediaSearchOptions:
|
|
$id: https://schema.beckn.io/MediaSearchOptions/v2.0
|
|
type: object
|
|
properties:
|
|
goals:
|
|
type: array
|
|
items:
|
|
type: string
|
|
enum: [visual-similarity, visual-object-detect, text-from-image, text-from-audio, semantic-audio-match, semantic-video-match]
|
|
augment_text_search:
|
|
type: boolean
|
|
default: true
|
|
restrict_results_to_media_proximity:
|
|
type: boolean
|
|
default: false
|
|
additionalProperties: false
|
|
|
|
Offer:
|
|
$id: 'https://schema.beckn.io/Offer/v2.1'
|
|
type: object
|
|
description: |
|
|
A generalized, cross-domain Offer that captures the terms under which
|
|
one or more Resources may be committed.
|
|
|
|
Core intent:
|
|
- Support multiple terms/eligibility/constraints/price points for the same Resource(s)
|
|
- Support dynamic / on-the-fly offers (e.g., bundling, combinational discounts,
|
|
eligibility changes, capacity-aware pricing)
|
|
|
|
This mirrors the role of Offer in current Beckn (and schema.org patterns),
|
|
but keeps the shape minimal and composable via `beckn:offerAttributes`.
|
|
required: ["@context", "@type", "id"]
|
|
properties:
|
|
"@context":
|
|
type: string
|
|
format: uri
|
|
description: JSON-LD context URI for the core Offer schema
|
|
enum: ["https://schema.beckn.io/Offer/v2.2/context.jsonld"]
|
|
"@type":
|
|
type: string
|
|
description: Type of the core Offer
|
|
enum: ["beckn:Offer"]
|
|
id:
|
|
type: string
|
|
description: Unique identifier of the offer.
|
|
descriptor:
|
|
description: Human / agent-readable description of this offer.
|
|
$ref: '#/components/schemas/Descriptor'
|
|
provider:
|
|
description: >
|
|
Provider of this offer.
|
|
- If the offer is published by the same provider as the item it is associated with,
|
|
use only the provider's `id` (string reference).
|
|
- If the offer is published by a different provider, include the full Provider object.
|
|
oneOf:
|
|
- type: object
|
|
description: Same provider as the item — identified by id only.
|
|
required: [id]
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Identifier of the provider (same as the item's provider).
|
|
- $ref: '#/components/schemas/Provider'
|
|
resourceIds:
|
|
type: array
|
|
description: References (IDs) to resources covered by this offer.
|
|
items:
|
|
$ref: '#/components/schemas/Resource/properties/id'
|
|
addOnIds:
|
|
type: array
|
|
description: IDs of optional extra Offers or Resources that can be attached.
|
|
items:
|
|
$ref: '#/components/schemas/AddOn/properties/id'
|
|
considerationIds:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Consideration/properties/id'
|
|
fulfillmentIds:
|
|
description: Details regarding the fulfillment of this offer
|
|
$ref: '#/components/schemas/Consideration'
|
|
validity:
|
|
$ref: '#/components/schemas/TimePeriod'
|
|
availableTo:
|
|
type: array
|
|
description: >
|
|
Optional visibility constraint indicating which network participants
|
|
(by participantId / networkId / role) are allowed to discover or
|
|
transact on this entity.
|
|
|
|
If omitted, the entity is assumed to be visible to all participants
|
|
in the addressed network(s).
|
|
items:
|
|
type: object
|
|
required: [type, id]
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [NETWORK, PARTICIPANT, ROLE]
|
|
description: Scope of visibility constraint.
|
|
id:
|
|
type: string
|
|
description: Identifier of the network, participant, or role.
|
|
offerAttributes:
|
|
$ref: '#/components/schemas/Attributes'
|
|
|
|
|
|
PriceSpecification:
|
|
type: object
|
|
properties:
|
|
priceUnit:
|
|
type: string
|
|
consideredValue:
|
|
type: number
|
|
components:
|
|
type: array
|
|
items:
|
|
type: object
|
|
required:
|
|
- lineId
|
|
- lineSummary
|
|
- value
|
|
- currency
|
|
properties:
|
|
lineId:
|
|
type: string
|
|
lineSummary:
|
|
type: string
|
|
value:
|
|
type: number
|
|
currency:
|
|
type: string
|
|
commitmentId:
|
|
$ref: '#/components/schemas/Commitment/properties/id'
|
|
quantity:
|
|
$ref: '#/components/schemas/Quantity'
|
|
|
|
ProcessingNotice:
|
|
$id: https://schema.beckn.io/ProcessingNotice/v2.0
|
|
type: object
|
|
required: [code, message]
|
|
properties:
|
|
code:
|
|
type: string
|
|
message:
|
|
type: string
|
|
details:
|
|
type: object
|
|
additionalProperties: true
|
|
|
|
|
|
Provider:
|
|
type: object
|
|
description: Schema definition for Provider in the Beckn Protocol v2.0.1
|
|
title: Provider
|
|
x-tags: [common]
|
|
properties:
|
|
'@context':
|
|
type: string
|
|
format: uri
|
|
default: "https://schema.beckn.io/"
|
|
'@type':
|
|
type: string
|
|
const: beckn:Provider
|
|
descriptor:
|
|
$ref: "#/components/schemas/Descriptor"
|
|
id:
|
|
description: Unique identifier for the provider
|
|
type: string
|
|
example: tech-store-001
|
|
locations:
|
|
description: Physical locations where the provider operates
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Location"
|
|
policies:
|
|
type: array
|
|
items:
|
|
type: object
|
|
providerAttributes:
|
|
$ref: "#/components/schemas/Attributes"
|
|
required:
|
|
- id
|
|
- descriptor
|
|
additionalProperties: false
|
|
|
|
Quantity:
|
|
$id: https://schema.beckn.io/Quantity/v2.0
|
|
description: Schema definition for Quantity in the Beckn Protocol v2.0.1
|
|
title: Quantity
|
|
type: object
|
|
properties:
|
|
maxQuantity:
|
|
description: Maximum quantity for this price
|
|
type: number
|
|
x-jsonld:
|
|
'@id': schema:Number
|
|
example: 100
|
|
minQuantity:
|
|
description: Minimum quantity for this price
|
|
type: number
|
|
x-jsonld:
|
|
'@id': schema:Number
|
|
example: 1
|
|
unitCode:
|
|
description: Unit code for the quoted price (e.g., KWH, MIN, H, MON)
|
|
type: string
|
|
x-jsonld:
|
|
'@id': schema:unitCode
|
|
example: KWH
|
|
unitQuantity:
|
|
description: Quantity of the unit
|
|
type: number
|
|
x-jsonld:
|
|
'@id': schema:Number
|
|
example: 1
|
|
unitText:
|
|
description: Unit for the quoted price (e.g., kWh, minute, hour, month)
|
|
type: string
|
|
x-jsonld:
|
|
'@id': schema:unitText
|
|
example: kWh
|
|
x-jsonld:
|
|
'@id': schema:QuantitativeValue
|
|
additionalProperties: false
|
|
x-tags:
|
|
- common
|
|
RatingForm: # Move to schema.beckn.io/RatingForm/v2.0
|
|
$id: https://schema.beckn.io/RatingForm/v2.0
|
|
$schema: "https://json-schema.org/draft/2020-12/schema"
|
|
description: A form designed to capture rating and feedback from a user. This can be used by both BAP and BPP to fetch ratings
|
|
and feedback of their respective users.
|
|
title: RatingForm
|
|
x-tags: [common]
|
|
type: object
|
|
properties:
|
|
'@context':
|
|
type: string
|
|
format: uri
|
|
const: "https://schema.beckn.io/"
|
|
'@type':
|
|
type: string
|
|
default: RatingForm
|
|
x-jsonld:
|
|
'@id': beckn:RatingForm
|
|
target:
|
|
description: The entity being rated
|
|
type: object
|
|
properties:
|
|
'@context':
|
|
type: string
|
|
format: uri
|
|
const: "https://schema.beckn.io/"
|
|
'@type':
|
|
type: string
|
|
default: RatingTarget
|
|
x-jsonld:
|
|
'@id': beckn:RatingTarget
|
|
id:
|
|
description: ID of the entity being rated (order/item/fulfillment/provider/agent).
|
|
type: string
|
|
ratingTargetType:
|
|
description: What is being rated.
|
|
type: string
|
|
enum: [Order, Fulfillment, FulfillmentStage, Provider, Agent]
|
|
range:
|
|
oneOf:
|
|
- type: object
|
|
properties:
|
|
bestRating:
|
|
description: Maximum of the rating scale (default 5 if omitted).
|
|
type: number
|
|
worstRating:
|
|
description: Minimum of the rating scale (default 1 or 0 if omitted).
|
|
type: number
|
|
- type: array
|
|
description: A custom rating range indexed from 0 to n
|
|
items:
|
|
type: object
|
|
properties:
|
|
index:
|
|
type: integer
|
|
minimum: 0
|
|
value:
|
|
$ref: "#/components/schemas/Descriptor"
|
|
feedbackForm:
|
|
description: A feedback form sent along with a rating request
|
|
type: object
|
|
feedbackRequired:
|
|
type: boolean
|
|
description: Specifies whether feedback after rating is required for acceptance of rating
|
|
required:
|
|
- '@context'
|
|
- '@type'
|
|
- target
|
|
- feedbackRequired
|
|
additionalProperties: false
|
|
|
|
RatingInput:
|
|
$id: https://schema.beckn.io/RatingInput/v2.0
|
|
title: RatingInput
|
|
description: |
|
|
A rating input form. Extends FormInput with the @type fixed to beckn:RatingForm,
|
|
indicating that this form instance is specifically a rating form.
|
|
allOf:
|
|
- type: object
|
|
- type: object
|
|
properties:
|
|
'@type':
|
|
type: string
|
|
const: 'beckn:RatingForm'
|
|
|
|
Rating:
|
|
$id: https://schema.beckn.io/Rating
|
|
oneOf:
|
|
- $ref: '#/components/schemas/Rating'
|
|
- title: Rating
|
|
type: object
|
|
description: Aggregated rating information for an entity. Aligns with schema.org/AggregateRating semantics.
|
|
properties:
|
|
'@context':
|
|
type: string
|
|
format: uri
|
|
const: https://schema.beckn.io/
|
|
'@type':
|
|
type: string
|
|
default: beckn:Rating
|
|
minValue:
|
|
description: Rating value (typically 0-5)
|
|
type: number
|
|
maxValue:
|
|
description: Number of ratings
|
|
type: integer
|
|
minimum: 0
|
|
x-jsonld:
|
|
'@id': schema:ratingCount
|
|
reviewText:
|
|
description: Optional textual review or comment
|
|
type: string
|
|
x-jsonld:
|
|
'@id': schema:reviewBody
|
|
additionalProperties: false
|
|
x-tags:
|
|
- common
|
|
|
|
Resource:
|
|
$id: 'https://schema.beckn.io/Resource/v2.0'
|
|
type: object
|
|
description: >
|
|
A minimal, domain-neutral abstraction representing any discoverable,
|
|
referenceable, or committable unit of value, capability, service,
|
|
entitlement, or asset within the network.
|
|
|
|
Examples:
|
|
- A retail product SKU, a mobility ride, a job role, a carbon credit unit,
|
|
a dataset/API entitlement, a training course, a clinic service slot.
|
|
|
|
Designed for composability through `resourceAttributes` where
|
|
domain packs can plug in their specific fields without changing the core.
|
|
required: ["@context", "@type", "id", "descriptor"]
|
|
properties:
|
|
"@context":
|
|
type: string
|
|
format: uri
|
|
description: JSON-LD context URI for the core Resource schema
|
|
"@type":
|
|
type: string
|
|
description: Type of the core Resource
|
|
const: "beckn:Resource"
|
|
id:
|
|
type: string
|
|
description: Globally unique identifier of the resource.
|
|
descriptor:
|
|
$ref: '#/components/schemas/Descriptor'
|
|
resourceAttributes:
|
|
description: All the properties of a resource that describe its value, its terms of usage, fulfillment, and consideration
|
|
$ref: '#/components/schemas/Attributes'
|
|
|
|
Settlement:
|
|
$id: 'https://schema.beckn.io/Settlement/v2.0'
|
|
type: object
|
|
properties:
|
|
"@context":
|
|
type: string
|
|
format: uri
|
|
description: The domain-specific context in which this settlement is taking place.
|
|
examples:
|
|
- https://schema.beckn.io/Settlement/2.0/context.jsonld
|
|
- https://schema.beckn.io/RetailOrderSettlement/2.0/context.jsonld
|
|
- https://schema.beckn.io/P2PTradeSettlement/context.jsonld
|
|
"@type":
|
|
type: string
|
|
description: Type of settlement within the context of this settlement
|
|
examples:
|
|
- "beckn:Settlement"
|
|
- "beckn:MonetaryTransfer"
|
|
- "beckn:TokenTransfer"
|
|
- "beckn:CreditSettlement"
|
|
- "beckn:AssetTransfer"
|
|
- "beckn:ServiceSettlement"
|
|
default: "beckn:MonetaryTransfer"
|
|
id:
|
|
type: string
|
|
considerationId:
|
|
$ref: '#/components/schemas/Consideration/properties/id'
|
|
status:
|
|
type: string
|
|
enum:
|
|
- DRAFT
|
|
- COMMITTED
|
|
- COMPLETE
|
|
settlementTerms:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/SettlementTerm'
|
|
settlementActions:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/SettlementAction'
|
|
settlementAttributes:
|
|
$ref: '#/components/schemas/Attributes'
|
|
|
|
|
|
SettlementAction:
|
|
$id: 'https://schema.beckn.io/SettlementAction/v2.0'
|
|
type: object
|
|
properties:
|
|
settlementTermId:
|
|
$ref: '#/components/schemas/SettlementTerm/properties/id'
|
|
status:
|
|
$ref: '#/components/schemas/Descriptor'
|
|
from:
|
|
$ref: '#/components/schemas/Participant'
|
|
to:
|
|
$ref: '#/components/schemas/Participant'
|
|
method:
|
|
$ref: '#/components/schemas/SettlementMethod'
|
|
instrument:
|
|
$ref: '#/components/schemas/SettlementInstrument'
|
|
|
|
SettlementInstrument:
|
|
type: object
|
|
properties:
|
|
'@context':
|
|
type: string
|
|
'@type':
|
|
type: string
|
|
id:
|
|
type: string
|
|
descriptor:
|
|
$ref: '#/components/schemas/Descriptor'
|
|
|
|
SettlementMethod:
|
|
type: object
|
|
properties:
|
|
'@context':
|
|
type: string
|
|
'@type':
|
|
type: string
|
|
id:
|
|
type: string
|
|
descriptor:
|
|
$ref: '#/components/schemas/Descriptor'
|
|
|
|
|
|
SettlementTerm:
|
|
$id: 'https://schema.beckn.io/SettlementTerm/v2.0'
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
committed:
|
|
type: boolean
|
|
default: false
|
|
commitments:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
$ref: '#/components/schemas/Commitment/properties/id'
|
|
required:
|
|
- id
|
|
performance:
|
|
required:
|
|
- id
|
|
oneOf:
|
|
- type: object
|
|
properties:
|
|
id:
|
|
$ref: '#/components/schemas/Performance/properties/id'
|
|
- $ref: '#/components/schemas/Performance'
|
|
type: string
|
|
trigger:
|
|
$ref: '#/components/schemas/ActionTrigger'
|
|
eligibleInstrument:
|
|
$ref: '#/components/schemas/SettlementInstrument'
|
|
schedule:
|
|
$ref: '#/components/schemas/Schedule'
|
|
from:
|
|
$ref: '#/components/schemas/Participant'
|
|
to:
|
|
$ref: '#/components/schemas/Participant'
|
|
eligibleMethods:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/SettlementMethod'
|
|
settlementTermAttributes:
|
|
$ref: '#/components/schemas/Attributes'
|
|
|
|
Schedule:
|
|
$id: 'https://schema.beckn.io/Schedule/v2.0'
|
|
title: Schedule
|
|
description: >
|
|
A schedule defines a repeating time period used to describe a regularly
|
|
occurring Event. At a minimum a schedule will specify repeatFrequency which
|
|
describes the interval between occurrences of the event. Additional information
|
|
can be provided to specify the duration of occurrences, an exception to the
|
|
schedule (exceptDate), and an end condition (either numberOfRepeats, repeatCount
|
|
or endDate).
|
|
|
|
Modeled after https://schema.org/Schedule.
|
|
type: object
|
|
properties:
|
|
byDay:
|
|
description: >
|
|
Defines the day(s) of the week on which a recurring Event takes place.
|
|
More specifically, to specify the day(s) of the week, use DayOfWeek;
|
|
for daily recurrence, use schema:DayOfWeek/Everyday.
|
|
A string value may also be used, for example "Sunday", "MO" (for Monday), or "MO TU" (for Monday and Tuesday).
|
|
oneOf:
|
|
- type: string
|
|
description: A day-of-week string (e.g. "Monday", "MO", "MO TU WE")
|
|
- type: array
|
|
items:
|
|
type: string
|
|
description: Day-of-week strings (e.g. "Monday", "MO")
|
|
byMonth:
|
|
description: >
|
|
Defines the month(s) of the year on which a recurring Event takes place.
|
|
Specified as an Integer between 1-12. January is 1.
|
|
oneOf:
|
|
- type: integer
|
|
minimum: 1
|
|
maximum: 12
|
|
- type: array
|
|
items:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 12
|
|
byMonthDay:
|
|
description: >
|
|
Defines the day(s) of the month on which a recurring Event takes place.
|
|
Specified as an Integer between 1-31.
|
|
oneOf:
|
|
- type: integer
|
|
minimum: 1
|
|
maximum: 31
|
|
- type: array
|
|
items:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 31
|
|
byMonthWeek:
|
|
description: >
|
|
Defines the week(s) of the month on which a recurring Event takes place.
|
|
Specified as an Integer between 1-5. For clarity, byMonthWeek is best
|
|
used in conjunction with byDay to indicate concepts like the first and
|
|
third Mondays of a month.
|
|
oneOf:
|
|
- type: integer
|
|
minimum: 1
|
|
maximum: 5
|
|
- type: array
|
|
items:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 5
|
|
duration:
|
|
description: >
|
|
The duration of the item (e.g., using ISO 8601 duration format).
|
|
type: string
|
|
format: duration
|
|
example: PT1H30M
|
|
endDate:
|
|
description: >
|
|
The end date and time of the item (in ISO 8601 date format).
|
|
type: string
|
|
format: date-time
|
|
example: "2025-12-31T23:59:59Z"
|
|
endTime:
|
|
description: >
|
|
The end time of the item. For a reserved event or service (e.g. EventReservation),
|
|
the time that it is expected to end. For actions that span a period of time,
|
|
when the action was performed. e.g. John wrote a book from January to December.
|
|
For media, including audio and video, it's the time offset of the end of a clip
|
|
within a larger file.
|
|
type: string
|
|
format: time
|
|
example: "18:00:00"
|
|
exceptDate:
|
|
description: >
|
|
Defines a Date or DateTime during which a scheduled Event will not take place.
|
|
The property allows exceptions to a Schedule to be specified. If an exception
|
|
is specified as a DateTime then only the event that would have started at that
|
|
specific date and time should be excluded from the schedule. If an exception is
|
|
specified as a Date then any event that is scheduled for that 24 hour period should
|
|
be excluded from the schedule. This allows a whole day to be excluded from the schedule
|
|
without having to itemise every scheduled event.
|
|
oneOf:
|
|
- type: string
|
|
format: date
|
|
- type: string
|
|
format: date-time
|
|
- type: array
|
|
items:
|
|
oneOf:
|
|
- type: string
|
|
format: date
|
|
- type: string
|
|
format: date-time
|
|
repeatCount:
|
|
description: >
|
|
Defines the number of times a recurring Event will take place.
|
|
type: integer
|
|
minimum: 1
|
|
repeatFrequency:
|
|
description: >
|
|
Defines the frequency at which Events will occur according to a schedule Schedule.
|
|
The intervals between events should be defined as a Duration of time.
|
|
A schema:repeatFrequency value can be specified as either an ISO 8601 string
|
|
(e.g. "P1W" for weekly) or by using one of the standard values from schema.org
|
|
such as "Daily", "Weekly", "Monthly", "Yearly".
|
|
type: string
|
|
example: P1W
|
|
scheduleTimezone:
|
|
description: >
|
|
Indicates the timezone for which the time(s) indicated in the Schedule are given.
|
|
The value provided should be among those listed in the IANA Time Zone Database.
|
|
type: string
|
|
example: Asia/Kolkata
|
|
startDate:
|
|
description: >
|
|
The start date and time of the item (in ISO 8601 date format).
|
|
type: string
|
|
format: date-time
|
|
example: "2025-01-01T00:00:00Z"
|
|
startTime:
|
|
description: >
|
|
The start time of the item. For a reserved event or service (e.g. EventReservation),
|
|
the time that it is expected to start. For actions that span a period of time,
|
|
when the action was performed. e.g. John wrote a book from January to December.
|
|
type: string
|
|
format: time
|
|
example: "09:00:00"
|
|
|
|
Signature:
|
|
title: Beckn HTTP Signature
|
|
description: |
|
|
A digitally signed authentication credential in the HTTP `Authorization` header.
|
|
Follows draft-cavage-http-signatures-12 as profiled by BECKN-006.
|
|
|
|
format:
|
|
```
|
|
Signature keyId="{subscriberId}|{uniqueKeyId}|{algorithm}",
|
|
algorithm="{algorithm}",created="{unixTimestamp}",expires="{unixTimestamp}",
|
|
headers="{signedHeaders}",signature="{base64Signature}"
|
|
```
|
|
|
|
| Attribute | Description |
|
|
|-----------|-------------|
|
|
| `keyId` | `{subscriberId}|{uniqueKeyId}|{algorithm}` — FQDN, registry UUID, algorithm |
|
|
| `algorithm` | MUST be `ed25519` |
|
|
| `created` | Unix timestamp when the signature was created |
|
|
| `expires` | Unix timestamp when the signature expires |
|
|
| `headers` | Space-separated signed headers. MUST include `(created)`, `(expires)`, `digest` |
|
|
| `signature` | Base64-encoded Ed25519 signature over the signing string |
|
|
|
|
Signing string:
|
|
`(created): {value}\n(expires): {value}\ndigest: BLAKE-512={digest}`
|
|
where `digest` is a BLAKE2b-512 hash of the request body, Base64-encoded.
|
|
type: string
|
|
pattern: '^Signature keyId="[^|"]+\|[^|"]+\|[^"]+",algorithm="[^"]+",created="\d+",expires="\d+",headers="[^"]+",signature="[A-Za-z0-9+/]+=*"$'
|
|
|
|
|
|
Support:
|
|
$id: https://schema.beckn.io/Support
|
|
description: Describes a support session
|
|
info
|
|
title: Support
|
|
type: object
|
|
properties:
|
|
'@context':
|
|
type: string
|
|
format: uri
|
|
default: https://schema.beckn.io/
|
|
'@type':
|
|
type: string
|
|
const: "beckn:Support"
|
|
orderId:
|
|
description: The order against which support is required
|
|
type: string
|
|
descriptor:
|
|
description: A description of the nature of support needed
|
|
$ref: '#/components/schemas/Descriptor'
|
|
channels:
|
|
description: Available support channels described in individual linked data JSON objects
|
|
type: array
|
|
minItems: 1
|
|
items:
|
|
$ref: '#/components/schemas/Attributes'
|
|
required:
|
|
- '@context'
|
|
- '@type'
|
|
additionalProperties: false
|
|
x-tags:
|
|
- common
|
|
|
|
Tracking:
|
|
$id: https://schema.beckn.io/Tracking
|
|
description: Information regarding live tracking of the fufillment of a contract
|
|
title: Tracking
|
|
type: object
|
|
properties:
|
|
'@context':
|
|
description: TBD
|
|
type: string
|
|
format: uri
|
|
default: https://schema.beckn.io/
|
|
'@type':
|
|
description: TBD
|
|
type: string
|
|
default: beckn:Tracking
|
|
refId:
|
|
description: Tracking reference ID for the tracking session. Could be the Order ID, Fulfillment ID, Fulfillment Stage ID, or any other unique tracking identifier
|
|
type: string
|
|
status:
|
|
type: string
|
|
enum:
|
|
- ACTIVE
|
|
- INACTIVE
|
|
- NOT-SUPPORTED
|
|
url:
|
|
description: Link/handle to off-network tracking UI or endpoint.
|
|
type: string
|
|
format: uri
|
|
|
|
required:
|
|
- '@context'
|
|
- '@type'
|
|
- url
|
|
- status
|
|
x-jsonld:
|
|
'@type': schema:TrackAction
|
|
trackingStatus: $.trackingStatus
|
|
schema:target: $.url
|
|
additionalProperties: false
|
|
x-tags:
|
|
- common
|
|
|
|
JSONLDHeaders:
|
|
type: object
|
|
properties:
|
|
'@context':
|
|
description: The JSON-LD context in which the attached object is being instantiated in.
|
|
type: string
|
|
format: uri
|
|
default: https://schema.beckn.io/
|
|
'@type':
|
|
description: The JSON-LD type in which the attached object
|
|
type: string
|
|
default: beckn:Tracking
|
|
required: ['@context', '@type']
|
|
|
|
TimePeriod:
|
|
$id: "https://schema.beckn.io/TimePeriod/v2.1"
|
|
description: Time window with date-time precision for availability/validity
|
|
title: TimePeriod
|
|
x-tags: [common]
|
|
type: object
|
|
properties:
|
|
'@type':
|
|
description: JSON-LD type for a date-time period
|
|
type: string
|
|
example: TimePeriod
|
|
startDate:
|
|
description: Start instant (inclusive)
|
|
type: string
|
|
format: date-time
|
|
example: '2025-01-27T09:00:00Z'
|
|
x-jsonld:
|
|
'@id': schema:startDate
|
|
endDate:
|
|
description: End instant (exclusive or inclusive per domain semantics)
|
|
type: string
|
|
format: date-time
|
|
example: '2025-12-31T23:59:59Z'
|
|
x-jsonld:
|
|
'@id': schema:endDate
|
|
startTime:
|
|
description: Start time of the time period
|
|
type: string
|
|
format: time
|
|
example: 09:00:00
|
|
x-jsonld:
|
|
'@id': schema:startTime
|
|
endTime:
|
|
description: End time of the time period
|
|
type: string
|
|
format: time
|
|
example: '22:00:00'
|
|
x-jsonld:
|
|
'@id': schema:endTime
|
|
required:
|
|
- '@type'
|
|
anyOf:
|
|
- required:
|
|
- startDate
|
|
- required:
|
|
- endDate
|
|
- required:
|
|
- startTime
|
|
- endTime
|
|
additionalProperties: false
|
|
|
|
# ── Ack schema (shared by Ack, AckNoCallback, NackBadRequest, NackUnauthorized responses) ──
|
|
AckSchema:
|
|
$id: 'https://schema.beckn.io/Ack'
|
|
title: Ack
|
|
oneOf:
|
|
- type: object
|
|
- type: object
|
|
properties:
|
|
status:
|
|
description: ACK if the request was accepted; NACK if rejected.
|
|
type: string
|
|
enum:
|
|
- ACK
|
|
- NACK
|
|
signature:
|
|
description: Counter-signature proving the receiver authenticated and processed the inbound request.
|
|
$ref: '#/components/schemas/CounterSignature'
|
|
error:
|
|
description: Optional error detail explaining why no callback will follow.
|
|
$ref: '#/components/schemas/Error'
|
|
required:
|
|
- status
|
|
- signature
|
|
|
|
responses:
|
|
Ack:
|
|
description: Synchronous receipt acknowledgement returned for every accepted Beckn request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AckSchema'
|
|
|
|
AckNoCallback:
|
|
description: |
|
|
Request received but no callback will follow (e.g. agents not found,
|
|
inventory unavailable, provider closed, context.try preview complete).
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/AckSchema'
|
|
- required:
|
|
- status
|
|
- signature
|
|
- error
|
|
|
|
|
|
NackBadRequest:
|
|
description: 'NACK — Bad Request: Malformed or invalid request; the server could not parse or validate the payload.'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/AckSchema'
|
|
- type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
const: NACK
|
|
error:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
NackUnauthorized:
|
|
description: Invalid or missing authentication credentials; signature could not be verified.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/AckSchema'
|
|
- type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
const: NACK
|
|
error:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
ServerError:
|
|
description: Internal failure on the network participant's application; the request could not be processed.
|
|
The response body MAY contain an `error` object with additional details.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
|