Public Release for Fall24 meta-release

CHANGELOG.md

@@ -3,15 +3,68 @@
 
 ## Table of contents
 
+- **[r1.2](#r12)**
 - **[r1.1](#r11)**
-- [v0.3.1](#v031)
+- **[v0.3.1](#v031)**
 
 
 **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 it has been released. For example, changes may be reverted before a release is published. For the best results, use the latest published release.**
 
+# r1.2
+
+## Release Notes
+
+This release contains the definition and documentation of
+* number-verification 1.0.0
+
+The API definition(s) are based on
+* Commonalities v0.4.0
+* Identity and Consent Management v0.2.0
+
+## number-verification 1.0.0
+
+**number-verification 1.0.0 is the release of the first stable version 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/r1.2/code/API_definitions/number-verification.yaml&nocors)
+  - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r1.2/code/API_definitions/number-verification.yaml)
+  - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r1.2/code/API_definitions/number-verification.yaml)
+
+**Main Changes**
+
+* API and test definitions updated to conform to the Commonalities v0.4.0 and Identity and Consent Management v0.2.0 guidelines included in the CAMARA Fall24 meta-release
+* Additional documentation & test cases added.
+* Changed name of the file itself from number_verification.yaml to number-verification.yaml
+
+
+### Added
+
+* User Story in documentation/API_documentation directory by @bigludo7 [PR118](https://github.com/camaraproject/NumberVerification/pull/118)
+* Test Definition in Test_Definitions directory by @AxelNennker [PR124](https://github.com/camaraproject/NumberVerification/pull/124)
+
+### Changed
+
+* Aligned with CAMARA design guidelines & Identity Consent management by @AxelNennker 
+* Make the '+' mandatory for the phone number by @fernandopradocabrillo [PR90](https://github.com/camaraproject/NumberVerification/pull/90)
+* Cosmetic change following megalinter integration by @bigludo7 [PR103](https://github.com/camaraproject/NumberVerification/pull/103)
+* Update Authorization and authentication part accordingly to ICM by @fernandopradocabrillo [PR88](https://github.com/camaraproject/NumberVerification/issues/88)
+* Adding a pattern for PhoneNumber in /verify by @maxl2287 [PR68](https://github.com/camaraproject/NumberVerification/issues/76)
+* Clarify use of 'user' and 'subscriber' wording by @AxelNennker [PR102](https://github.com/camaraproject/NumberVerification/pull/102)
+* Clarify that the sequence diagram in the yaml documentation is an example by @bigludo7 [PR139](https://github.com/camaraproject/NumberVerification/pull/139)
+
+### Fixed
+
+* Replaced OAuth2 auth code flow by OIDC auth code flow by @AxelNennker [PR109](https://github.com/camaraproject/NumberVerification/pull/109)
+
+### Removed
+
+* Removed documentation (replaced by doc in the yaml) by @AxelNennker [PR137](https://github.com/camaraproject/NumberVerification/pull/1379)
+
+## New Contributors
+* N/A
 
 
-# r1.1 - rc
+# r1.1
 
 ## Release Notes
 

README.md

@@ -27,19 +27,15 @@ Repository to describe, develop, document and test the NumberVerification API fa
 ## Status and released versions
 
 * 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 latest pre-release of CAMARA Number Verification API is 1.0.0-rc.1 This is the release candidate of the first stable version of the API**. It is suitable for implementors.
-* The Release Tag is [r1.1](https://github.com/camaraproject/NumberVerification/releases/tag/r1.1).
-  - API definition **with inline documentation**:
-    - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r1.1/code/API_definitions/number_verification.yaml)
-    - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r1.1/code/API_definitions/number_verification.yaml&nocors)
-    - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r1.1/code/API_definitions/number_verification.yaml)
-
 
-* The previous version 0.3.1 is available within the [release-0.3.1 branch](https://github.com/camaraproject/NumberVerification/tree/release-0.3.1):
+* `NEW`: Release r1.2 with version 1.0.0 of the API number-verification is available [here](https://github.com/camaraproject/NumberVerification/tree/r1.2)
   - API definition **with inline documentation**:
-    - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/release-0.3.1/code/API_definitions/CAMARA/number_verification.yaml)
-    - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/release-0.3.1/code/API_definitions/CAMARA/number_verification.yaml&nocors)
-    - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/release-0.3.1/code/API_definitions/CAMARA/number_verification.yaml)
+    - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r1.2/code/API_definitions/number-verification.yaml)
+    - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r1.2/code/API_definitions/number-verification.yaml&nocors)
+    - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r1.2/code/API_definitions/number-verification.yaml)
+
+* Previous releases and pre-releases of the repository are available in https://github.com/camaraproject/NumberVerification/releases 
+* For changes see [CHANGELOG.md](https://github.com/camaraproject/NumberVerification/blob/main/CHANGELOG.md)
 
 
 ## Contributorship and mailing list
@@ -50,4 +46,4 @@ Repository to describe, develop, document and test the NumberVerification API fa
 
 ## Relevant Information
 
-Since April 4th 2024 WG meeting minutes are placed in [Number Verification Wiki Confluence site](https://wiki.camaraproject.org/display/CAM/Number+Verification)
+Since April 4th 2024 WG meeting minutes are placed in [Number Verification Wiki Confluence site](https://wiki.camaraproject.org/display/CAM/NumberVerification)

code/API_definitions/number_verification.yaml → code/API_definitions/number-verification.yaml

@@ -30,6 +30,8 @@ info:
     # Sequence Diagram
     Number Verification API uses the **standard [OIDC Authorization Code Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)**. The following diagram will help to clarify the end-to-end process, including previous steps prior to this API call.
 
+    Note that the diagram shows just an example of a direct integration from developer's application and MNO's authserver and API, other scenarios of indirect integration via Aggregator/Channel Partner should also be considered. Specific authorization flows may apply, as defined by e.g. GSMA Open Gateway (OGW).
+
     ![UML Sequence Diagram](https://raw.githubusercontent.com/camaraproject/NumberVerification/main/documentation/API_documentation/assets/uml_v0.3.jpg)
 
     **Additional details:**
@@ -50,13 +52,13 @@ info:
 
     # Further info and support
     [GSMA Mobile Connect Verified MSISDN specification](https://www.gsma.com/identity/wp-content/uploads/2022/12/IDY.54-Mobile-Connect-Verified-MSISDN-Definition-and-Technical-Requirements-1.0.pdf) was used as source of input for this API.  For more about Mobile Connect, please see [Mobile Connect website](https://mobileconnect.io/).
-  version: wip
+  version: 1.0.0
   x-camara-commonalities: 0.4.0
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
 servers:
-  - url: '{apiRoot}/number-verification/v1rc1'
+  - url: '{apiRoot}/number-verification/v1'
     variables:
       apiRoot:
         default: http://localhost:9091
@@ -79,7 +81,7 @@ paths:
       operationId: phoneNumberVerify
       parameters:
         - in: header
-          name: X-Correlator
+          name: x-correlator
           required: false
           description: Correlation id for the different services
           schema:
@@ -94,7 +96,7 @@ paths:
         '200':
           description: OK
           headers:
-            X-Correlator:
+            x-correlator:
               description: Correlation id for the different services
               schema:
                 type: string
@@ -129,7 +131,7 @@ paths:
       operationId: phoneNumberShare
       parameters:
         - in: header
-          name: X-Correlator
+          name: x-correlator
           required: false
           description: Correlation id for the different services
           schema:
@@ -138,7 +140,7 @@ paths:
         '200':
           description: OK
           headers:
-            X-Correlator:
+            x-correlator:
               description: Correlation id for the different services
               schema:
                 type: string

code/Test_Definitions/NumberVerification_device_phone_number_share.feature → code/Test_Definitions/number-verification-device-phone-number-share.feature

@@ -1,11 +1,9 @@
-
-
 @NumberVerification_device_phone_number_share
 Feature: Camara Number Verification API device phone number share
 
 # Input to be provided by the implementation to the tests
 # References to OAS spec schemas refer to schemas specified in
-# https://raw.githubusercontent.com/camaraproject/NumberVerification/main/code/API_definitions/number_verification.yaml
+# /code/API_definitions/number-verification.yaml
 #
 # Implementation indications:
 # * api_root: API root of the server URL
@@ -15,7 +13,7 @@ Feature: Camara Number Verification API device phone number share
 # * a mobile device with SIM card with NUMBERVERIFY_SHARE_PHONENUMBER2
 
   Background: Common Number Verification phone number share setup
-    Given the resource "/device-phone-number/v0"  as  base url
+    Given the resource "/device-phone-number/v1"  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" is set to a UUID value

code/Test_Definitions/NumberVerification_verify.feature → code/Test_Definitions/number-verification-verify.feature

@@ -1,11 +1,9 @@
-
-
 @NumberVerification_verify
 Feature: Camara Number Verification API verify
 
 # Input to be provided by the implementation to the tests
 # References to OAS spec schemas refer to schemas specified in
-# https://raw.githubusercontent.com/camaraproject/NumberVerification/main/code/API_definitions/number_verification.yaml
+# /code/API_definitions/number-verification.yaml
 #
 # Implementation indications:
 # * api_root: API root of the server URL
@@ -16,10 +14,8 @@ Feature: Camara Number Verification API verify
 # * a mobile device with SIM card with NUMBERVERIFY_VERIFY_MATCH_PHONENUMBER_HASHED1
 # * a mobile device with SIM card with NUMBERVERIFY_VERIFY_MATCH_PHONENUMBER_HASHED2
 
-
-
   Background: Common Number Verification verify setup
-    Given the resource "/number-verification/v0"  as  base url
+    Given the resource "/number-verification/v1"  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" is set to a UUID value
@@ -39,7 +35,7 @@ Feature: Camara Number Verification API verify
     And the response property "$.code" is "INVALID_ARGUMENT"
     And the response property "$.message" contains a user friendly text
     And they acquired a valid access token associated with NUMBERVERIFY_VERIFY_MATCH_PHONENUMBER1 through OIDC authorization code flow
-    
+
     Examples:
       | phone_number_value |
       | string_value       |
@@ -49,7 +45,6 @@ Feature: Camara Number Verification API verify
       | 123                |
       | ++49565456787      |
 
-
   @NumberVerification_verify100_match_true
   Scenario:  verify phone number NUMBERVERIFY_VERIFY_MATCH_PHONENUMBER1, network connection and access token matches NUMBERVERIFY_VERIFY_MATCH_PHONENUMBER1
     Given they use the base url
@@ -78,7 +73,6 @@ Feature: Camara Number Verification API verify
     Then the response status code is 200
     And the response property "$.devicePhoneNumberVerified" is true
 
-
   @NumberVerification_verify101_match_false
   Scenario:  verify phone number NUMBERVERIFY_VERIFY_MATCH_PHONENUMBER1 but access token is associated with NUMBERVERIFY_VERIFY_MATCH_PHONENUMBER2
     Given they use the base url
@@ -157,7 +151,7 @@ Feature: Camara Number Verification API verify
     And the response property "$.message" is "New authentication is required."
 
   @NumberVerification_verify203_both_phone_number_and_hashed_in_request
-  Scenario:  verify phone number but no phonenumber in request
+  Scenario:  verify phone number but providing both plain and hashed phone number in the body
     Given they use the base url
     And the resource is "/verify"
     And one of the scopes associated with the access token is number-verification:verify
@@ -188,7 +182,6 @@ Feature: Camara Number Verification API verify
     And the response property "$.status" is 403
     And the response property "$.code" is "INVALID_TOKEN_CONTEXT"
     And the response property "$.message" is "Phone number cannot be deducted from access token context."
-
 
   @NumberVerification_phone_number_verify205_must_have_used_network_authentication
   Scenario:  verify phone number with valid access token but network authentication was not used

documentation/API_documentation/NumberVerification-Readiness-Checklist.md

@@ -1,22 +1,24 @@
 # API Readiness Checklist
 
-Checklist for number_verification 1.0.0-rc.1 in release r1.1
+Checklist for number-verification 1.0.0 in release r1.2
 
 | Nr | API release assets  | alpha | release-candidate |  public-release<br>initial | public-release<br> stable | Status | Comments |
 |----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:----:|
-|  1 | API definition                               |   M   |         M         |    M    |    M   |   Y   | [link](/code/API_definitions/number_verification.yaml) |
+|  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    |      |
 |  3 | Guidelines from ICM applied                  |   O   |         M         |    M    |    M   |   Y   |      |
 |  4 | API versioning convention applied            |   M   |         M         |    M    |    M   |   Y   |      |
-|  5 | API documentation                            |   M   |         M         |    M    |    M   |   Y   | Embed documentation into API spec - [link](/code/API_definitions/number_verification.yaml)  |
-|  6 | User stories                                 |   O   |         O         |    O    |    M   |   tbd   | [PR #129](https://github.com/camaraproject/NumberVerification/pull/129/files) |
-|  7 | Basic API test cases & documentation         |   O   |         M         |    M    |    M   |   tbd   | [PR #124](https://github.com/camaraproject/NumberVerification/pull/124/files) |
-|  8 | Enhanced API test cases & documentation      |   O   |         O         |    O    |    M   |   tbd  | [PR #124](https://github.com/camaraproject/NumberVerification/pull/124/files) |
-|  9 | Test result statement                        |   O   |         O         |    O    |    M   |   tbd   | link |
-
+|  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   | Fall24 EXCEPTION: Test results not available (*) |
 | 10 | API release numbering convention applied     |   M   |         M         |    M    |    M   |   Y   |      |
-| 11 | Change log updated                           |   M   |         M         |    M    |    M   |   N   | [link](/CHANGELOG.md) |
-| 12 | Previous public-release was certified        |   O   |         O         |    O    |    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)    |
+
+(*) If you encounter issues with the provided test files (.feature), please create an issue in the API Sub-Project to signal these issues so they can be fixed in a patch release.
+
 
 To fill the checklist:
 - in the line above the table, replace the api-name, api-version and the rx.y by their actual values for the current API version and release.