Align network-health-assessment and network-traffic-analysis with Commonalities r4.4

[hdamker]

Problem description

release-plan.yaml declares commonalities_release: r4.4 for release r2.1 (#102), and the r4.4 common files are now in code/common/ (#103). This issue collects the points that need to be addressed to bring network-health-assessment and network-traffic-analysis to Commonalities 0.9.0 (r4.4).

Note that CI validation is currently green — 0 errors, with two P-027 warnings and five hints. Most of the items below are not covered by any validation rule; they come from the r4.4 changelog and the CAMARA API Design Guide. A passing pipeline should not be read as r4.4 alignment.

Both APIs are at 0.2.0 targeting rc, with no published stable version and no snapshot currently open, so the changes below can be made directly on main.

Expected behavior

Metadata and documentation

• Set x-camara-commonalities: "0.9.0" in both specs (r4.4 VERSION.yaml is 0.9.0), for accuracy on main — currently "0.7". For network-traffic-analysis this is already covered by fix: reference DateTime schema for accessDate #104.
• Re-copy the additional-error-responses CAMARA:MANDATORY:BEGIN..END block in info.description from code/common/info-description-templates.yaml into both specs. This is the P-027 warning: paragraph 3 changed in Commonalities#693, so "The applicable Commonalities Release can be identified in the API Readiness Checklist document associated to this API version." becomes "The applicable Commonalities Release can be identified from the x-camara-commonalities field, the changelog and the metadata of the released API version."
• Add the blank line after :BEGIN (Commonalities#660) to the authorization-and-authentication and request-body-strictness blocks in both specs, if not already there — those two are otherwise already at r4.4 wording.
• Set externalDocs.description to exactly Product documentation at CAMARA in both specs — currently Project documentation at CAMARA. This is the P-039 hint.

Error responses — migrate off the deprecated Generic<status> responses

r4.4 deprecates all Generic<status> responses in favour of a minimal named catalogue plus a shared example pool, and plans their removal next cycle (Commonalities#665). Both specs currently define their own Generic400, Generic401, Generic403 and Generic404 locally, each against a bare ErrorInfo with no restriction on status or code. The catalogue entries restrict both to exactly the codes the operation can return, so replacing them removes the duplication and tightens the documented contract at the same time.

• In both specs: Generic401 → CAMARA_common.yaml#/components/responses/Unauthenticated401, Generic403 → PermissionDenied403, Generic404 → NotFound404.
• network-health-assessment: Generic400 → BadRequest400.
• network-traffic-analysis: Generic400 → BadRequestWithRange400, which keeps both INVALID_ARGUMENT and OUT_OF_RANGE.
• Delete all four local response definitions from each spec once nothing references them.

NotFound404 rather than IdentifierNotFound404 is the right entry for both operations: r4.4 scopes the latter to APIs that identify their subject by device or phone number, whereas the subject here is a networkId passed as a query parameter.

Using BadRequest400 for getHealthScores drops OUT_OF_RANGE and so resolves #97. That operation accepts only a UUID-formatted networkId and a closed netType enum, so every invalid value is an INVALID_ARGUMENT schema violation and no input can produce OUT_OF_RANGE. getTrafficAnalysis keeps the code, because endDate before startDate is a genuine out-of-range condition.

Common component reuse

The r4.4 API template (artifacts/api-templates/sample-service.yaml) references the common security scheme, x-correlator parameter and x-correlator header rather than redefining them. Both specs currently redefine all three locally, with text identical to the common definitions.

• Replace the local x-correlator parameter and header in both specs with $refs to CAMARA_common.yaml#/components/parameters/x-correlator and #/components/headers/x-correlator.
• Replace the local openId security scheme in both specs with a $ref to CAMARA_common.yaml#/components/securitySchemes/openId, as the template does.
• network-traffic-analysis: reference the common parameters/page and parameters/perPage instead of declaring the parameters locally around the already-referenced Page and PerPage schemas. The common descriptions additionally document the 400 INVALID_ARGUMENT rejection required by Design Guide §4.1.1.
• network-traffic-analysis: replace the local ipv4Address definition with a $ref to CAMARA_common.yaml#/components/schemas/SingleIpv4Address. Constraints are identical (format: ipv4, maxLength: 15); only the example value differs. This covers the first part of Reuse common IPv4 schema and add IPv6 support for ipv4Address #93. r4.4 also adds SingleIpv6Address (Commonalities#654), which makes the IPv6 counterpart requested in Reuse common IPv4 schema and add IPv6 support for ipv4Address #93 available — worth considering in the same pass.
• network-health-assessment: reference the common DateTime schema for scoringTime instead of the constraint-identical local definition, keeping nullable: true and the field-specific description as siblings of the allOf — the pattern network-traffic-analysis already uses for startDate and endDate.

accessDate is handled separately in #104 and #90.

Pagination

• network-traffic-analysis: document the out-of-range page case. Design Guide §4.1.5 requires a request with page greater than totalPages to return 200 with an empty collection and an accurate pagination object. The spec currently documents only the no-data case, and its single EmptyResponse example (totalCount: 0, totalPages: 0) illustrates only that.

Test definitions

• Normalise the OAS pointers to the #/ prefix used by the r4.4 test template (Commonalities#678, #683) — network-health-assessment-getHealthScores.feature and network-traffic-analysis-getTrafficAnalysis.feature each use #/components/schemas/XCorrelator in their Background but the un-prefixed form in the success scenario.
• network-health-assessment-getHealthScores.feature: remove network_health_assessment_getHealthScores_03_out_of_range_scenario, following the BadRequest400 change above. Its example ("an invalid netType value") is an INVALID_ARGUMENT case already covered by scenario 02. This is the second part of getHealthScores declares an unreachable 400 OUT_OF_RANGE, test scenario mislabeled #97.

Additional context

Related issues that are linked rather than covered here: #90 and #104 (accessDate), the IPv6 part of #93, #94 (no defined error for a startDate/endDate misaligned with the chosen frequency), and #96 (missing test scenarios for the app filter, pagination and the empty/null success responses).

[hdamker]

@cnzj-Gc I let my agent create this issue so that you have a full view of the changes to completely fulfill the "x-commonalities: 0.9.0" statement in the API.

[cnzj-Gc]

@hdamker Thanks for pointing this out; I will keep an eye on the changes brought by the r4.4 specification while handling the remaining issues and gradually complete all corrections.

[tanjadegroot]

Hi Team,

for traceability, please create focused PRs on main when addressing the points in the above list with descriptive titles that make it understandable by API Consumers.

Note: You can also prefix these PR titles with the name of the Changelog category (e.g. "(Added) " (or use "(Admin)" if the update is internal to CAMARA) to ease updating the Changelog once the Release review PR is ready.

Many thanks !