Document deferred CAMARA validation warnings and hints (Sync26 - r4.4 commonalities)

[albertoramosmonagas]

Problem description

CAMARA Validation currently passes with findings for the main branch (as of September 18, 2026):

CAMARA Validation — PASS (with findings)
Profile: standard | Branch: main | Trigger: pull_request
Result: 0 errors, 10 warnings, 4 hints

Following the synchronization with Commonalities r4.4 (PR #146), the API definition has been updated with common files. However, validation findings remain that should be addressed to achieve clean validation status.

Findings Overview

• Emit annotations: code/API_definitions/population-density-data.yaml#L259
  [S-035] Notification callback content type must include 'application/cloudevents+json', found: application/json
• Emit annotations: code/API_definitions/population-density-data.yaml#L1
  [P-015] No event type enum values found in code/API_definitions/population-density-data.yaml — subscription APIs should define EventType schemas | Suggestion: Define a named event type schema (e.g. ApiEventType) that constrains the CloudEvent type value via allOf, rather than inlining the enum directly in CloudEvent.properties.type.enum. See the implicit-events API template in Commonalities artifacts/api-templates/ (tracked in Add sample-implicit-events.yaml API template for callback-based event pattern Commonalities#608).
• Emit annotations: code/API_definitions/population-density-data.yaml#L456
  [S-313] Schema of type string should specify a format, pattern, enum, or const. | Suggestion: Acceptable if free-form field or implementation-dependent — no fix needed.

Full validation report: https://github.com/camaraproject/PopulationDensityData/actions/runs/35848676802/job/107140885889?pr=149

Expected behavior

Address the deferred validation findings in a follow-up pull request:

• Change the notification callback media type to application/cloudevents+json
• Add descriptions for all array items and schema properties
• Update the apiRoot description to match standard CAMARA wording
• Review and implement guidance from validation hints

Alternative solution

Event-related findings could be addressed by synchronizing the API definition with the Commonalities implicit-events template once it becomes stable, rather than implementing changes independently in this repository.

[albertoramosmonagas]

Before fixing the P-015 and S-035 warnings, we should confirm whether this callback is an event notification or an asynchronous response.

If it only returns the final result of a previously accepted request, it should follow the asynchronous-response guidance being clarified in Commonalities PR #575 , rather than CloudEvents.

The warnings are already documented and are therefore not blockers for the RC. My proposal is to keep the current contract for the snapshot and review the callback model after the release, avoiding last-minute API and test changes based on a validation rule that may be too broad.

[albertoramosmonagas]

Hi, all resolvable warnings and hints have been done in PR #149. P-015 does not apply because Population Density Data is not an events API per se, and the discussion is in the commonalities section. The same applies to S-035, and S-313 is a free-form field, so it would not be necessary. I've update the issue and to keep it open for the future

[tanjadegroot]

Hi @albertoramosmonagas, to my understanding is that the way CAMARA implements asynchronous responses is by using a callback with content based on the cloud-event format. You may want some specialist to confirm this (@rartych @hdamker).

If so, this required aligning this API to the Commonalities r4.4 as per sample-implicit-events.

As the plan is to release the first stable version of this API this needs to be fixed ASAP IMHO. One might also consider doing another initial version of the API if this discussion needs more time.

[PedroDiez]

Hi @albertoramosmonagas, to my understanding is that the way CAMARA implements asynchronous responses is by using a callback with content based on the cloud-event format. You may want some specialist to confirm this (@rartych @hdamker).

If so, this required aligning this API to the Commonalities r4.4 as per sample-implicit-events.

As the plan is to release the first stable version of this API this needs to be fixed ASAP IMHO. One might also consider doing another initial version of the API if this discussion needs more time.

Hi @tanjadegroot,

In the case of this API, it is not being talk about an API with Subscriptions (explicit or implicit), but an API that may answer in real time (sync) or offline (async). In CAMARA Commonalities, CAMARA-API-Design-Guide.md#5761-asynchronous-responses, there is a section where it is defined some guidelines for this kind of APIs, indicating why it does not have to use CloudEvents model in async response and use instead the same model as a sync one, but in request sink (and also sinkCredential can be) is used (to provide that response in an asynchronous way).

I think the topic is raised by the linter due to somehow if the sink concept appears in an API it behaves as it was a subscription-based API.
So for this case, i think we should skip this linter warning.

cc @albertoramosmonagas, @rartych, @hdamker

[tanjadegroot]

Hi all, I have done a check on the API inline documentation and see several clarifications needed to help the API consumer. Please see #152 for details.

For the rest all is OK for this release publlication, so let me know if you want to do the documentation updates before or after this release.