From d98a9b6bcc802b495894232ce2e1bb976376bf69 Mon Sep 17 00:00:00 2001 From: Rajaneesh Date: Tue, 2 Jul 2024 21:36:11 +0530 Subject: [PATCH] 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 --- api/meta/build/meta.yaml | 4 +- api/meta/components/index.yaml | 4 +- api/registry/build/registry.yaml | 4 +- api/registry/components/index.yaml | 4 +- api/transaction/README.md | 4 +- api/transaction/build/transaction.yaml | 4 +- api/transaction/components/index.yaml | 4 +- ...KN-001-Layering-Network-Policy-Draft-01.md | 50 ++++++++++++++++--- 8 files changed, 57 insertions(+), 21 deletions(-) diff --git a/api/meta/build/meta.yaml b/api/meta/build/meta.yaml index 4992bd2a..0e88b6c2 100644 --- a/api/meta/build/meta.yaml +++ b/api/meta/build/meta.yaml @@ -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: diff --git a/api/meta/components/index.yaml b/api/meta/components/index.yaml index ca6df550..5e67900e 100644 --- a/api/meta/components/index.yaml +++ b/api/meta/components/index.yaml @@ -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: diff --git a/api/registry/build/registry.yaml b/api/registry/build/registry.yaml index 8f1f3777..4e6f09f0 100644 --- a/api/registry/build/registry.yaml +++ b/api/registry/build/registry.yaml @@ -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: diff --git a/api/registry/components/index.yaml b/api/registry/components/index.yaml index 6319cc5d..988d57e6 100644 --- a/api/registry/components/index.yaml +++ b/api/registry/components/index.yaml @@ -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: diff --git a/api/transaction/README.md b/api/transaction/README.md index ddaae61c..4f15122b 100644 --- a/api/transaction/README.md +++ b/api/transaction/README.md @@ -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: [] diff --git a/api/transaction/build/transaction.yaml b/api/transaction/build/transaction.yaml index 1e6956bf..6524aec2 100644 --- a/api/transaction/build/transaction.yaml +++ b/api/transaction/build/transaction.yaml @@ -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: diff --git a/api/transaction/components/index.yaml b/api/transaction/components/index.yaml index f0a6537a..b9ebabf1 100644 --- a/api/transaction/components/index.yaml +++ b/api/transaction/components/index.yaml @@ -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: [] diff --git a/docs/BECKN-001-Layering-Network-Policy-Draft-01.md b/docs/BECKN-001-Layering-Network-Policy-Draft-01.md index b8849dd6..b3676562 100644 --- a/docs/BECKN-001-Layering-Network-Policy-Draft-01.md +++ b/docs/BECKN-001-Layering-Network-Policy-Draft-01.md @@ -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 +``` \ No newline at end of file