Fix review issues for r4.1

code/API_definitions/population-density-data.yaml

@@ -1,4 +1,4 @@
 openapi: 3.0.3
 info:
   title: Population Density Data
   description: |
@@ -44,6 +44,16 @@
     When an asynchronous response is requested, the 202 response of the API will include an `operationId` property. This `operationId` property will
     also be sent in the callback notification. The purpose of the `operationId` is to correlate an asynchronous response with its corresponding request.
 
+    Using `credentialType: PRIVATE_KEY_JWT` requires the JWT authentication parameters to be pre-configured
+    out-of-band between the API consumer and the API provider as part of the onboarding process. No response of
+    this API returns `sinkCredential`, so the provider's `jwksUri` is never conveyed in-band. Unlike an event
+    subscription, this operation creates no resource to read back, the same static `jwksUri` would be repeated on
+    every `202` response, and the callback may be delivered before the API consumer has processed that response.
+    If `PRIVATE_KEY_JWT` is requested and no JWK Set is configured for the API consumer, the API returns the
+    error response `422 PRIVATE_KEY_JWT_NOT_CONFIGURED`. A failure to authenticate against the API consumer's
+    authorization server when the callback is delivered cannot be detected while the request is being processed,
+    and is therefore reported in the callback with property `status` set to `OPERATION_NOT_COMPLETED`.
+
     # API Functionality
 
     Once a developer specifies (1) the area (either as a polygon shape or as a list of geohashes),
@@ -102,7 +112,7 @@
     The standard behaviour of the API is synchronous, although for large
     area requests the API may behave asynchronously. An API invoker can enforce
     asynchronous behaviour by providing a callback URL (`sink`)
-    is in the request, in this case the API sends a callback
+    in the request, in this case the API sends a callback
     to the callback URL provided with the result of the request. If `sink` is
     included, it is RECOMMENDED for the client to provide as well the `sinkCredential`
     property to protect the notification endpoint. In the current version,`sinkCredential.credentialType`
@@ -142,8 +152,8 @@
     In cases where personal data is processed by the API and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design.
     <!-- CAMARA:MANDATORY:authorization-and-authentication:END -->
 
-    Population Density Data API ensures the usage of anonymized information and do not treat personal data neither as input nor output.
-    Therefore, the access to Population Density Data API is defined as Client Credentials - 2-legged. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the latest detailed specification of this authentication/authorization flow.
+    Population Density Data API ensures the usage of anonymized information and does not treat personal data as either input or output.
+    Therefore, the access to Population Density Data API is defined as Client Credentials - 2-legged. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the latest detailed specification of this authentication/authorization flow.
 
     <!-- CAMARA:MANDATORY:additional-error-responses:BEGIN -->
     # Additional CAMARA error responses
@@ -177,7 +187,7 @@
     variables:
       apiRoot:
         default: http://localhost:9091
         description: API root
 tags:
   - name: Population Density Data
     description: Operations to retrieve population density information.
@@ -233,7 +243,7 @@
                 - $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator"
               requestBody:
                 description: Population density data result.
                 content:
                   application/json:
                     schema:
                       $ref: '#/components/schemas/PopulationDensityAsyncResponse'
@@ -430,7 +440,7 @@
           maxItems: 168
         status:
           $ref: '#/components/schemas/ResponseStatus'
         statusInfo:
           type: string
           maxLength: 512
           description: Information about the status, mandatory when property `status` is `OPERATION_NOT_COMPLETED` for adding extra information about the error.
@@ -456,7 +466,7 @@
               $ref: '#/components/schemas/OperationId'
           required:
             - operationId
     OperationId:
       type: string
       maxLength: 256
       description: The unique identifier of the asynchronous operation that is returned when the operation is initiated.
@@ -475,7 +485,7 @@
         - PART_OF_AREA_NOT_SUPPORTED
         - AREA_NOT_SUPPORTED
         - OPERATION_NOT_COMPLETED
     TimedPopulationDensityData:
       type: object
       properties:
         startTime:
@@ -519,7 +529,7 @@
       properties:
         geohash:
           $ref: '#/components/schemas/Geohash'
         dataType:
           type: string
           enum:
             - NO_DATA
@@ -534,13 +544,13 @@
           NO_DATA: '#/components/schemas/NoData'
           LOW_DENSITY: '#/components/schemas/LowDensity'
           DENSITY_ESTIMATION: '#/components/schemas/DensityEstimation'
     NoData:
       allOf:
         - $ref: '#/components/schemas/CellPopulationDensityData'
     LowDensity:
       allOf:
         - $ref: '#/components/schemas/CellPopulationDensityData'
     DensityEstimation:
       allOf:
         - $ref: '#/components/schemas/CellPopulationDensityData'
         - type: object
@@ -578,6 +588,7 @@
           - Indicated `endTime` is earlier than the `startTime` ("code": "POPULATION_DENSITY_DATA.INVALID_END_TIME", "message": "Indicated endTime is earlier than the startTime")
           - Indicated time period is partially in the past and partially in the future ("code": "POPULATION_DENSITY_DATA.INVALID_TIME_PERIOD", "message": "time period is partially in the past and partially in the future")
           - Indicated time period is greater than the maximum allowed (More than maximum hours between startTime and endTime) ("code": "POPULATION_DENSITY_DATA.MAX_TIME_PERIOD_EXCEEDED", "message": "Indicated time period is greater than the maximum allowed (More than maximum hours between startTime and endTime)")
+          - `sinkCredential.credentialType` is set to `PRIVATE_KEY_JWT` but no JWK Set is configured for the API consumer ("code": "PRIVATE_KEY_JWT_NOT_CONFIGURED", "message": "No JWK Set configured for PRIVATE_KEY_JWT authentication.")
       headers:
         x-correlator:
           $ref: '../common/CAMARA_common.yaml#/components/headers/x-correlator'
@@ -603,17 +614,19 @@
                       - POPULATION_DENSITY_DATA.INVALID_END_TIME
                       - POPULATION_DENSITY_DATA.MAX_TIME_PERIOD_EXCEEDED
                       - POPULATION_DENSITY_DATA.INVALID_TIME_PERIOD
+                      - PRIVATE_KEY_JWT_NOT_CONFIGURED
           examples:
             GENERIC_400_INVALID_ARGUMENT:
               value:
                 status: 400
                 code: INVALID_ARGUMENT
                 message: Invalid input
             GENERIC_400_INVALID_CREDENTIAL:
+              description: Invalid sink credential type
               value:
                 status: 400
                 code: INVALID_CREDENTIAL
-                message: "Only Access token is supported"
+                message: Only Access token or Private key JWT are supported
             GENERIC_400_INVALID_TOKEN:
               value:
                 status: 400
@@ -687,6 +700,7 @@
                       - POPULATION_DENSITY_DATA.UNSUPPORTED_PRECISION
                       - POPULATION_DENSITY_DATA.UNSUPPORTED_SYNC_RESPONSE
                       - POPULATION_DENSITY_DATA.UNSUPPORTED_AREA_TYPE
+                      - PRIVATE_KEY_JWT_NOT_CONFIGURED
           examples:
             POPULATION_DENSITY_DATA_422_UNSUPPORTED_REQUEST:
               value:
@@ -711,6 +725,12 @@
                 status: 422
                 code: POPULATION_DENSITY_DATA.UNSUPPORTED_AREA_TYPE
                 message: The requested areaType is not supported by the MNO
+            GENERIC_422_PRIVATE_KEY_JWT_NOT_CONFIGURED:
+              description: Private key JWT sink credential type is used but no configuration was pre-shared
+              value:
+                status: 422
+                code: PRIVATE_KEY_JWT_NOT_CONFIGURED
+                message: No JWK Set configured for PRIVATE_KEY_JWT authentication.
   examples:
     PopulationDensitySupportedAreaResponseExample:
       description: Population density supported area response example

code/Test_definitions/population-density-data.feature

@@ -155,7 +155,7 @@ Feature: CAMARA Population Density Data API, vwip
     And the response header "Content-Type" is "application/json"
     And the response header "x-correlator" has same value as the request header "x-correlator"
     And the response includes property "$.operationId"
-    And there have been some problem processing the request asynchronously
+    And there has been a problem processing the request asynchronously
     And the request with the response body will be received at the address of the request property "$.sink" with property "$.operationId" equal to response property "$.operationId"
     And the request will have header "Authorization" set to "Bearer " + the value of the request property "$.sinkCredential.accessToken"
     And the request body complies with the OAS schema at "/components/schemas/PopulationDensityAsyncResponse"
@@ -270,7 +270,7 @@ Feature: CAMARA Population Density Data API, vwip
 
   @population_density_data_400.06_invalid_url
   Scenario: Invalid sink
-    Given the request body property "$.sink" is not set to an url
+    Given the request body property "$.sink" is not set to a URL
     When the request "retrievePopulationDensity" is sent
     Then the response status code is 400
     And the response header "x-correlator" has same value as the request header "x-correlator"

documentation/API_documentation/Population-Density-Data_User_Story.md

@@ -2,7 +2,7 @@
 
  Items | Details |
 |---|---|
-| **Summary** | The API provides estimation of Population Density for a specific area at a future period time, considering historical anonymized information of the network connected devices in the requested area.|
+| **Summary** | The API provides estimation of Population Density for a specific area at a future period of time, considering historical anonymized information of the network connected devices in the requested area.|
 | **Actors and scope** | **Scope:** Retrieve predicted population density for a defined polygonal area and time interval; provide insights into population patterns to support strategic planning. <br><br> **Use Case 1 — Drone Route Planning:** Identify zones to avoid due to high population-related risk; determine optimal time window to fly between two points (A–B) minimizing population exposure. <br><br> **Use Case 2 — Urban Planning:** Data-driven optimization of public services/resource allocation; support simulation and impact assessment for urban mobility and infrastructure planning.|
 | **Pre-conditions** | The client must provide: <br> - **Requested Area (Required):** Polygonal area defined by coordinates forming a closed loop. <br> - **Start Time (Required):** Future controlled time of departure. <br> - **End Time (Required):** Future controlled time of arrival. <br> - **Precision (Optional):** Geohash precision level. <br> - **Sink (Optional):** Destination system/endpoint for delivery. <br> - **Sink Credentials (Optional):** AuthN/AuthZ details to access the sink.|
 | **Activities / Steps** | 1) The client submits a request including the inputs above. <br> 2) The API responds **synchronously** (response body) or **asynchronously** (delivered to sink), including: <br> - **a) Cell Coordinates:** Geohash string representing the cell. <br> - **b) Population Density Metrics:** per cell in **1-hour intervals** with **min / avg / max** population. <br> - **c) Data Type (k-anonymity):** `Low_Density` (below threshold, cannot disclose) or `Density_Estimation` (values available and disclosed).|