Add new changes for Sync26 (geohashlist+Commonalities & ICM)

[albertoramosmonagas]

What type of PR is this?

Add one of the following kinds:

• enhancement/feature

What this PR does / why we need it:

This PR extends the Population Density Data API with support for a new optional area type: GEOHASHLIST. POLYGON remains the mandatory area type for all MNO implementations, while GEOHASHLIST is introduced as an optional area representation for providers that can support geohash-based requests. Changes included:

• Added new GEOHASHLIST value to areaType.
• Added GeohashList and Geohash schemas.
• Added geohash validation pattern: ^[0-9bcdefghjkmnpqrstuvwxyz]{1,12}$
• Restricted the precision field to POLYGON requests only. If precision is provided together with GEOHASHLIST, the API returns 400 INVALID_ARGUMENT.
• Added new 422 error:POPULATION_DENSITY_DATA.UNSUPPORTED_AREA_TYPE to indicate that the requested areaType is valid in the API specification but not supported by the MNO.
• Refactored CellPopulationDensityData.geohash to reference the common Geohash schema, ensuring the same geohash definition is reused in both request and response models.
• Updated the API description to clarify the expected GEOHASHLIST behaviour:
  • geohashes may have mixed precision levels;
  • geohashes do not need to be contiguous;
  • geohashes outside MNO coverage return NO_DATA;
  • if the full geohash list is outside the supported area, the response status is AREA_NOT_SUPPORTED.

This PR also clarifies the behaviour for unsupported precision values:

• If the precision value or geohash length is outside the schema range 1–12, the request is rejected with 400 INVALID_ARGUMENT.
• If the value is within the valid schema range but not supported by the MNO, the API returns:422 POPULATION_DENSITY_DATA.UNSUPPORTED_PRECISION

This applies both to the precision field for POLYGON requests and to the length of each geohash in GEOHASHLIST requests.

Alignment with CAMARA Commonalities

This PR also aligns the API definition with the updated CAMARA Commonalities requirements.

Commonalities version update (Comm-Spring26-005)

• Updated x-camara-commonalities from 0.6 to the full semantic version 0.8.0.

Notification credentials (Comm-Spring26-004)

The sinkCredential model has been aligned with the updated CAMARA notification credential model:

• Removed the deprecated PLAIN and REFRESHTOKEN credential types.
• Added the PRIVATE_KEY_JWT credential type, which supports token renewal through an authorization server.
• The supported credential types are now:
  • ACCESSTOKEN
  • PRIVATE_KEY_JWT

Implementation note: the Nexo platform does not currently support PRIVATE_KEY_JWT. It has been included in the API specification for forward compatibility. For the current one-time callback use case, the credential type used in practice remains ACCESSTOKEN.

Reinforced input validation (Comm-Spring26-006)

Validation constraints have been added to string, array and integer fields in accordance with the CAMARA OWASP-oriented validation guidelines. These constraints do not invalidate any value that was already valid under the previous API definition.

For Population Density Data, the following limits have been added:

Field type	Fields and constraints
Strings	Geohash: maxLength: 12; sink: maxLength: 2048; request and interval startTime / endTime: maxLength: 64; OperationId: maxLength: 256; statusInfo: maxLength: 512
Arrays	geohashes: maxItems: 1000; timedPopulationDensityData: maxItems: 168; CellPopulationDensityDataArray: maxItems: 10000
Integers	precision: format: int32; maxPplDensity, minPplDensity and pplDensity: format: int32, minimum: 0, maximum: 2147483647

Error model and traceability

The standard CAMARA validation constraints have also been applied to the shared error and tracing fields:

• ErrorInfo includes the standard description and constraints:
  • status: format: int32, with values restricted to the range 100–599;
  • code and message: standard maxLength constraints.
• x-correlator includes the standard CAMARA description and maxLength constraint.

Backwards compatibility

All Commonalities-related changes are backwards compatible, except for the removal of the deprecated PLAIN and REFRESHTOKEN notification credential types. No practical impact is expected, as the previous API specification already required the use of ACCESSTOKEN.

Which issue(s) this PR fixes:

Fixes #110, #109, #105

Special notes for reviewers:

This PR is based on conversations that can be followed at #110.

Changelog input

 release-note
Added optional `GEOHASHLIST` area support with reusable geohash schemas, clarified precision handling, and introduced `POPULATION_DENSITY_DATA.UNSUPPORTED_AREA_TYPE` for valid but unsupported area types.

Additional documentation

This section can be blank.

docs

[rartych]

population-density-data-API-Readiness-Checklist.md - file should be deleted for Sync26 - release automation takes care about all needed information

[rartych]

For asynchronous responses CloudEvents format is not recommended now, see detailed guidelines:
https://github.com/camaraproject/Commonalities/blob/main/documentation/CAMARA-API-Design-Guide.md#5761-asynchronous-responses

[albertoramosmonagas]

Thanks, @rartych. We reviewed the current design again against the updated Commonalities guidance.

Our understanding is that the API already follows the recommended asynchronous-response pattern:

• the initial request can return 202 Accepted;
• the final result is delivered once to the callback URL provided through sink;
• the callback payload uses the API-specific response model, rather than a CloudEvents envelope;
• sink and sinkCredential are used consistently with the CAMARA callback design.

Therefore, although the callback mechanism was previously described as CloudEvents-based, the actual payload does not use the CloudEvents structure (specversion, type, source, data, etc.). It appears to be the same domain response model delivered asynchronously, which is precisely what the current Design Guide recommends.

Could you please confirm which specific part of the current API definition you consider non-compliant with section 5.7.6.1? If we are overlooking a CloudEvents-specific structure or another required change, we will address it.

[albertoramosmonagas]

Hi @camaraproject/population-density-data_codeowners, The deadline for creating the snapshot is before July 31. Can we merge this PR to create it?

[jgarciahospital]

LGTM