Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Releasing the version 1.1.1 of Beckn core protocol specification #434

Merged
merged 1 commit into from
Jul 17, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Releasing the version 1.1.1 of Beckn core specification
	- Changing openAPI version from 3.0 to 3.1 in core protocol specification
	- Minor change: change version from 1.0.0 to 1.1.1 in example documentation
rajaneeshk90 committed Jul 2, 2024
commit d98a9b6bcc802b495894232ce2e1bb976376bf69
4 changes: 2 additions & 2 deletions api/meta/build/meta.yaml
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
openapi: 3.0.0
openapi: 3.1.0
info:
title: Beckn Protocol Meta API
description: This document contains all the meta API endpoints that are implemented by the network participants. The information returned from these endpoints typically contain cacheable information.
version: 1.0.0
version: 1.1.1
security:
- SubscriberAuth: []
paths:
4 changes: 2 additions & 2 deletions api/meta/components/index.yaml
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
openapi: 3.0.0
openapi: 3.1.0
info:
title: Beckn Protocol Meta API
description: This document contains all the meta API endpoints that are implemented by the network participants. The information returned from these endpoints typically contain cacheable information.
version: "1.0.0"
version: "1.1.1"
security:
- SubscriberAuth: []
paths:
4 changes: 2 additions & 2 deletions api/registry/build/registry.yaml
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
openapi: 3.0.0
openapi: 3.1.0
info:
title: Beckn Protocol Registry Infrastructure API
description: 'This document contains the API specification for the Registry infrastructure of a beckn-enabled network. The Registry API forms the trust layer of beckn protocol. When implemented, they enable creation of an infrastructure that allow trusted transactions between network participants to take place by means of digital signature authentication. The core infrastructure is called the Network Registry or simply, Registry. Any network participant that is listed on the registry can be assumed to have successfully passed the certfication and compliance process of the network, and hence be trusted to transact with.'
version: 1.0.0
version: 1.1.1
security:
- SubscriberAuth: []
paths:
4 changes: 2 additions & 2 deletions api/registry/components/index.yaml
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
openapi: 3.0.0
openapi: 3.1.0
info:
title: Beckn Protocol Registry Infrastructure API
description: This document contains the API specification for the Registry infrastructure of a beckn-enabled network. The Registry API forms the trust layer of beckn protocol. When implemented, they enable creation of an infrastructure that allow trusted transactions between network participants to take place by means of digital signature authentication. The core infrastructure is called the Network Registry or simply, Registry. Any network participant that is listed on the registry can be assumed to have successfully passed the certfication and compliance process of the network, and hence be trusted to transact with.
version: "1.0.0"
version: "1.1.1"
security:
- SubscriberAuth: []
paths:
4 changes: 2 additions & 2 deletions api/transaction/README.md
Original file line number Diff line number Diff line change
@@ -39,11 +39,11 @@ AddOn:
- In the file, you will see the following

```
openapi: 3.0.0
openapi: 3.1.0
info:
title: Beckn Protocol Core
description: Beckn Core API specification
version: "1.0.0"
version: "1.1.1"

security:
- SubscriberAuth: []
4 changes: 2 additions & 2 deletions api/transaction/build/transaction.yaml
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
openapi: 3.0.0
openapi: 3.1.0
info:
title: Beckn Protocol Core
description: Beckn Core Transaction API specification
version: 1.1.0
version: 1.1.1
security:
- SubscriberAuth: []
paths:
4 changes: 2 additions & 2 deletions api/transaction/components/index.yaml
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
openapi: 3.0.0
openapi: 3.1.0
info:
title: Beckn Protocol Core
description: Beckn Core Transaction API specification
version: "1.1.0"
version: "1.1.1"

security:
- SubscriberAuth: []
50 changes: 43 additions & 7 deletions docs/BECKN-001-Layering-Network-Policy-Draft-01.md
Original file line number Diff line number Diff line change
@@ -43,7 +43,7 @@ Readers of this document must:

1. Have knowledge of the core protocol specification
2. Have knowledge of the Architecture of Open Commerce Networks instantiated using beckn protocol.
3. Have knowledge of Open API 3.0 Specification
3. Have knowledge of Open API 3.1.0 Specification


# Context
@@ -101,11 +101,11 @@ After reading this document, the reader should be able to
A network policy is a set of rules that must be published by the architects of beckn-enabled open commerce networks as a machine-readable specification to allow its participants to create protocol validation middleware in their implementations. This specification should **inherit** all the attributes of the core specification along with some additional constraints on the usage of the specification during network transactions.


## Inheritance and Polymorphism in Open API 3.0
## Inheritance and Polymorphism in Open API 3.1.0

The core specification currently exists in the form of an Open API Specification 3.0 document with some reserved modifications. To layer policy on the specification, beckn protocol governance allows layering of policies by way of configuration. This configuration is done on the core Open API document by using the inheritance and polymorphism feature of Open API Specification 3.0. Inheritance and polymorphism are terms used in Object Oriented Design and are applicable to beckn protocol specifications as well. To learn more about Inheritance and Polymorphism as a generic concept, click here.
The core specification currently exists in the form of an Open API Specification 3.1.0 document with some reserved modifications. To layer policy on the specification, beckn protocol governance allows layering of policies by way of configuration. This configuration is done on the core Open API document by using the inheritance and polymorphism feature of Open API Specification 3.1.0. Inheritance and polymorphism are terms used in Object Oriented Design and are applicable to beckn protocol specifications as well. To learn more about Inheritance and Polymorphism as a generic concept, click here.

In Open API 3.0, inheritance and Polymorphism are enabled using the “allOf”, “oneOf” and “anyOf” keywords.
In Open API 3.1.0, inheritance and Polymorphism are enabled using the “allOf”, “oneOf” and “anyOf” keywords.


### The allOf keyword
@@ -146,7 +146,7 @@ This keyword allows the validator to validate a value against exactly one of the
This keyword allows the validator to validate a value against exactly one or more of the subschemas out of several schemas.


## Applying Network-Specific Policies using Open API 3.0
## Applying Network-Specific Policies using Open API 3.1.0


### Adding enumerations, defaults and min / max values
@@ -225,7 +225,7 @@ RatingPolicy1:

### Adding alternative schemas

Sometimes it is possible to have requests and responses that can be described by several alternative schemas. In OpenAPI 3.0, to describe such a model, we can use the oneOf or anyOf keywords. For example, while transmitting payment terms from BPP to the BAP via the **on_init** action, multiple payment endpoints can be sent in the _params_ property of the **Payment** schema as shown below.
Sometimes it is possible to have requests and responses that can be described by several alternative schemas. In OpenAPI 3.1.0, to describe such a model, we can use the oneOf or anyOf keywords. For example, while transmitting payment terms from BPP to the BAP via the **on_init** action, multiple payment endpoints can be sent in the _params_ property of the **Payment** schema as shown below.


```
@@ -387,7 +387,7 @@ Tags:

All these extensions must be published as part of a separate document called **Network Implementation Policy**

It is recommended that this document be published along with the API specification of that network using the **externalDocs** attribute as defined by Open API Specification 3.0
It is recommended that this document be published along with the API specification of that network using the **externalDocs** attribute as defined by Open API Specification 3.1.0

More Examples:

@@ -423,3 +423,39 @@ Rating:
$ref: '#/components/schemas/FeedbackUrl/properties/params/properties/feedback_id'
required: false
```
### Adding conditional blocks

OpenAPI 3.1 introduces support for advanced conditional checks. These capabilities allow for sophisticated validation scenarios, such as conditional requirements (if, then, else constructs), dependent schemas, and more nuanced combinatory logic with allOf, anyOf, oneOf, and not. This enables more precise and flexible validation of API request and response data.

For example, in a confirmation request from a BAP to a BPP, if the payment type is PRE-ORDER, the payment.params.transaction_id must be included in the request. Here’s how to define this conditional rule in the OpenAPI specification:

```
if:
properties:
message:
properties:
order:
properties:
payments:
type: array
items:
properties:
type:
const: "PRE-ORDER"
then:
properties:
message:
properties:
order:
properties:
payments:
type: array
items:
properties:
params:
properties:
transaction_id:
type: string
required:
- transaction_id
```