Prepare r3.1

CHANGELOG.md

@@ -3,6 +3,7 @@
 
 ## Table of contents
 
+- **[r3.1](#r31) Fall25**
 - **[r2.4](#r24) Spring25**
 - ~~[r2.3](#r23)~~
 - **[r2.2](#r22)**
@@ -22,6 +23,44 @@ The below sections record the changes for each API version in each release as fo
 * for subsequent release-candidate(s), only the delta to the previous release-candidate
 * for a public release, the consolidated changes since the previous public release
 
+# r3.1
+
+This **public release** contains the definition and documentation of
+* number-verification 2.1.0-rc.1
+
+The API definition(s) are based on
+* Commonalities v0.6.0-rc.1
+* Identity and Consent Management v0.4.0-rc.1
+
+## number-verification 2.1.0-rc.1
+
+**number-verification 2.1.0-rc.1 is the first pre-release for v2.0.0-rc.1 of the NumberVerification API.**
+
+- API definition **with inline documentation**:
+  - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r3.1/code/API_definitions/number-verification.yaml&nocors)
+  - [View it on Swagger Editor](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r3.1/code/API_definitions/number-verification.yaml)
+  - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r3.1/code/API_definitions/number-verification.yaml)
+
+### Added
+
+- Add pattern validation for hashedPhoneNumber by @ravindrapalaskar17 in https://github.com/camaraproject/NumberVerification/pull/188
+- Documented Error Responses info.description section by @bigludo7 in https://github.com/camaraproject/NumberVerification/pull/199
+- Include documentation to use with JWT-bearer auth flow by @fernandopradocabrillo in https://github.com/camaraproject/NumberVerification/pull/206
+
+### Changed
+
+- Update x-correlator format by @bigludo7 in https://github.com/camaraproject/NumberVerification/pull/200
+- Update test plan by @fernandopradocabrilo in https://github.com/camaraproject/NumberVerification/pull/204
+
+### Removed
+
+- Remove AUTHENTICATION_REQUIRED error by @fernandopradocabrillo in https://github.com/camaraproject/NumberVerification/pull/206
+
+## New Contributors
+* @ravindrapalaskar17 made their first contribution in https://github.com/camaraproject/NumberVerification/pull/188
+
+**Full Changelog**: https://github.com/camaraproject/NumberVerification/compare/r2.4...r3.1
+
 # r2.4
 
 ## Release Notes

README.md

@@ -27,7 +27,13 @@ Incubating API Repository to evolve and maintain the definitions and documentati
 
 * Note: Please be aware that the project will have frequent updates to the main branch. There are no compatibility guarantees associated with code in any branch, including main, until a new release is created. For example, changes may be reverted before a release is created. **For best results, use the latest available release**.
 
-* The public release r2.4 with version 2.0.0 of the API number-verification is available [here](https://github.com/camaraproject/NumberVerification/tree/r2.4)
+* **NEW**: The pre-release r3.1 with version 2.1.0-rc.1 of the API number-verification is available [here](https://github.com/camaraproject/NumberVerification/tree/r3.1)
+  - 2.1.0-rc.1 Number Verification definition **with inline documentation**:
+    - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r3.1/code/API_definitions/number-verification.yaml)
+    - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r3.1/code/API_definitions/number-verification.yaml&nocors)
+    - [View it on Swagger Editor](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r3.1/code/API_definitions/number-verification.yaml)
+
+* The latest public release r2.4 with version 2.0.0 of the API number-verification is available [here](https://github.com/camaraproject/NumberVerification/tree/r2.4)
   - 2.0.0 Number Verification definition **with inline documentation**:
     - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r2.4/code/API_definitions/number-verification.yaml)
     - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r2.4/code/API_definitions/number-verification.yaml&nocors)

code/API_definitions/number-verification.yaml

@@ -27,7 +27,10 @@ info:
     ## Authentication Request with a temporary token
 
     If the API Consumer has a TS.43 temporary token created on the mobile device then this API works over all connections e.g. WiFi taking advantage of the SIM-Based authentication.
-    The API Consumer sends the temporary token to their backend which sends a CIBA Authentication Request, as described in the current release [CAMARA APIs Access and User Consent Management](https://github.com/camaraproject/IdentityAndConsentManagement), with a parameter "login_hint=operatortoken:<temporary token>".
+    The API Consumer sends the temporary token to their backend which either:
+      - Sends a CIBA Authentication Request, as described in the current release [CAMARA APIs Access and User Consent Management](https://github.com/camaraproject/IdentityAndConsentManagement), with a parameter `login_hint=operatortoken:<temporary token>`.
+      - Or sends a JWT-Bearer token request as described in [CAMARA APIs Access and User Consent Management](https://github.com/camaraproject/IdentityAndConsentManagement), with the TS.43 token in the `sub` claim of the JWT assertion with the format `"operatortoken:<temporary token>"`.
+
     How the API Consumers get a TS.43 temporary token and how this token is sent to their backend, is out-of-scope of the API definition.
 
     ## Authentication Request without a temporary token
@@ -80,16 +83,16 @@ info:
 
     As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API.
 
-  version: wip
-  x-camara-commonalities: 0.5
+  version: 2.1.0-rc.1
+  x-camara-commonalities: 0.6
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
 externalDocs:
   description: Project documentation at CAMARA
   url: https://github.com/camaraproject/NumberVerification
 servers:
-  - url: '{apiRoot}/number-verification/vwip'
+  - url: '{apiRoot}/number-verification/v2rc1'
     variables:
       apiRoot:
         default: http://localhost:9091
@@ -287,20 +290,13 @@ components:
                   code:
                     enum:
                       - UNAUTHENTICATED
-                      - AUTHENTICATION_REQUIRED
           examples:
             GENERIC_401_UNAUTHENTICATED:
-              description: Request cannot be authenticated
+              description: Request cannot be authenticated and a new authentication is required
               value:
                 status: 401
                 code: UNAUTHENTICATED
-                message: Request not authenticated due to missing, invalid, or expired credentials.
-            GENERIC_401_AUTHENTICATION_REQUIRED:
-              description: New authentication is needed, authentication is no longer valid
-              value:
-                status: 401
-                code: AUTHENTICATION_REQUIRED
-                message: New authentication is required.
+                message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required.
     PhoneNumberVerificationPermissionDenied403:
       description: |
         Client does not have sufficient permission.

code/Test_Definitions/number-verification-phoneNumberShare.feature

@@ -1,4 +1,4 @@
-Feature: CAMARA Number Verification API, vwip - Operation phoneNumberShare
+Feature: CAMARA Number Verification API, v2.1.0-rc.1 - Operation phoneNumberShare
 
   # Input to be provided by the implementation to the tester
   #
@@ -10,7 +10,7 @@ Feature: CAMARA Number Verification API, vwip - Operation phoneNumberShare
 
 
   Background: Common phoneNumberShare setup
-    Given the resource "/number-verification/vwip" as base url
+    Given the resource "/number-verification/v2rc1" as base url
     And the header "Content-Type" is set to "application/json"
     And the header "Authorization" is set to a valid access token
     And the header "x-correlator" complies with the schema at "#/components/schemas/XCorrelator"

code/Test_Definitions/number-verification-phoneNumberVerify.feature

@@ -1,4 +1,4 @@
-Feature: CAMARA Number Verification API, vwip - Operation phoneNumberVerify
+Feature: CAMARA Number Verification API, v2.1.0-rc.1 - Operation phoneNumberVerify
 
   # Input to be provided by the implementation to the tester
   #
@@ -11,7 +11,7 @@ Feature: CAMARA Number Verification API, vwip - Operation phoneNumberVerify
 
 
   Background: Common phoneNumberVerify setup
-    Given the resource "/number-verification/vwip" as base url
+    Given the resource "/number-verification/v2rc1" as base url
     And the header "Content-Type" is set to "application/json"
     And the header "Authorization" is set to a valid access token
     And the header "x-correlator" complies with the schema at "#/components/schemas/XCorrelator"

documentation/API_documentation/number-verification-API-Readiness-Checklist.md

@@ -1,21 +1,22 @@
 # API Readiness Checklist
 
-Checklist for number-verification v2.0.0 in release r2.4
+Checklist for number-verification v2.1.0-rc.1 in release r3.1
 
 | Nr | API release assets  | alpha | release-candidate |  public-release<br>initial | public-release<br> stable | Status | Reference information |
 |----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:----:|
-|  1 | API definition                               |   M   |         M         |    M    |    M   |   Y   | [link](/code/API_definitions/number-verification.yaml) |
-|  2 | Design guidelines from Commonalities applied |   O   |         M         |    M    |    M   |   Y   |  [r2.3](https://github.com/camaraproject/Commonalities/releases/tag/r2.3)   |
-|  3 | Guidelines from ICM applied                  |   O   |         M         |    M    |    M   |   Y   |  [r2.3](https://github.com/camaraproject/IdentityAndConsentManagement/releases/tag/r2.3)   |
+|  1 | API definition                               |   M   |  M         |    M    |    M   |   Y   | [link](/code/API_definitions/number-verification.yaml) |
+|  2 | Design guidelines from Commonalities applied |   O   |         M         |    M    |    M   |   Y   |  [r3.2](https://github.com/camaraproject/Commonalities/releases/tag/r3.2)   |
+|  3 | Guidelines from ICM applied                  |   O   |         M         |    M    |    M   |   Y   |  [r3.2](https://github.com/camaraproject/IdentityAndConsentManagement/releases/tag/r3.2)   |
 |  4 | API versioning convention applied            |   M   |         M         |    M    |    M   |   Y   |      |
 |  5 | API documentation                            |   M   |         M         |    M    |    M   |   Y   | Embedded documentation into API spec - [link](/code/API_definitions/number-verification.yaml)  |
 |  6 | User stories                                 |   O   |         O         |    O    |    M   |   Y   | [get](/documentation/API_documentation/NumberVerification_device_phone_number_User_Story.md) [verify](/documentation/API_documentation/NumberVerification_verify_User_Story.md) |
-|  7 | Basic API test cases & documentation         |   O   |         M         |    M    |    M   |   Y   | [get](code/Test_Definitions/number-verification-device-phone-number-share.feature) [verify](/code/Test_Definitions/number-verification-verify.feature) |
-|  8 | Enhanced API test cases & documentation      |   O   |         O         |    O    |    M   |   Y   | [get](code/Test_Definitions/number-verification-device-phone-number-share.feature) [verify](code/Test_Definitions/number-verification-verify.feature) |
-|  9 | Test result statement                        |   O   |         O         |    O    |    M   |   N   | see [issue #166](https://github.com/camaraproject/NumberVerification/issues/166) |
+|  7 | Basic API test cases & documentation         |   O   |         M         |    M    |    M   |   Y   | [get](code/Test_Definitions/number-verification-phoneNumberShare.feature) [verify](/code/Test_Definitions/number-verification-phoneNumberVerify.feature) |
+|  8 | Enhanced API test cases & documentation      |   O   |         O         |    O    |    M   |   Y   | [get](code/Test_Definitions/number-verification-phoneNumberShare.feature) [verify](code/Test_Definitions/number-verification-phoneNumberVerify.feature) |
+|  9 | Test result statement                        |   O   |         O         |    O    |    M   |   N   |     |
 | 10 | API release numbering convention applied     |   M   |         M         |    M    |    M   |   Y   |      |
 | 11 | Change log updated                           |   M   |         M         |    M    |    M   |   Y   | [link](/CHANGELOG.md) |
 | 12 | Previous public-release was certified        |   O   |         O         |    O    |    M   |   Y   | [link](https://www.open-gateway.com/operators-map)    |
+| 13 | API description (for marketing)              |   O   | O          | M | M | Y | [wiki link](https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/81134263/NumberVerification+API+description) |
 
 
 To fill the checklist: