Adapt qos-profiles API spec and tests to Commonalities r4.3 (0.8.0)

[RandyLevensalor]

What type of PR is this?

• enhancement/feature

What this PR does / why we need it:

Adapts the qos-profiles API specification and its test definitions to CAMARA Commonalities r4.3 (Commonalities 0.8.0), using the analysis done by the Commonalities Working Group (Analysis of Commonalities 0.8.0) and the ConsentManagement #29 alignment as references.

API specification (qos-profiles.yaml):

• Updated x-camara-commonalities from 0.6 to 0.8.0.
• Replaced duplicated definitions with $ref into code/common/CAMARA_common.yaml: openId security scheme, x-correlator parameter/header, Device, ErrorInfo, and responses Generic400, Generic401, Generic429; GenericDevice404 now references the common Generic404 (identical code set).
• Removed the now-unused local schemas XCorrelator, PhoneNumber, NetworkAccessIdentifier, DeviceIpv4Addr, SingleIpv4Addr, Port, DeviceIpv6Address (rule S-211).
• Kept local code-subset responses where the common definition lists codes that do not apply to this API: Generic403 (PERMISSION_DENIED only), Generic404 (NOT_FOUND only, for getQosProfile), Generic422 (SERVICE_NOT_APPLICABLE, UNSUPPORTED_IDENTIFIER, UNNECESSARY_IDENTIFIER).
• Added the mandatory info.description section markers (text copied as-is from code/common/info-description-templates.yaml): authorization-and-authentication, additional-error-responses, and the new request-body-strictness.
• Added maxLength/maxItems constraints (rules S-312 / S-309) to the remaining local schemas: QosProfile.description, Availability and its networks array, countryName, and the retrieveQoSProfiles 200 response array.

Test definitions (both .feature files):

• Aligned with the r4.3 sample-service-template: added Happy Path Scenarios / Error Scenarios banners and Syntax Error / Service Error subsections.
• Renumbered error-scenario tags to double-digit format (400.01, 401.01, 403.01, 404.01, 429.01, …).
• Added 429.01_too_many_requests and invalid_x-correlator scenarios (and 400.03_empty_request_body for retrieveQoSProfiles); added x-correlator/Content-Type response-header assertions to the device error scenarios.
• Updated schema references that moved to common (XCorrelator, PhoneNumber, DeviceIpv4Address, DeviceIpv6Address, NetworkAccessIdentifier) to point at ../common/CAMARA_common.yaml.

Which issue(s) this PR fixes:

Fixes #573

Special notes for reviewers:

Two deliberate deviations from the generic Commonalities template, for your attention:

1. identifying-device-from-access-token mandatory block not embedded verbatim. The standard opt-in block states the device object "MUST be provided" with a two-legged token and defines a 422 MISSING_IDENTIFIER case. In qos-profiles, however, device is an optional filter — retrieveQoSProfiles legitimately returns all profiles when no device is supplied, so MISSING_IDENTIFIER does not apply. The existing, accurate "Identifying the device from the access token" section (documenting the optional filter and the 422 UNNECESSARY_IDENTIFIER behaviour) has been kept instead. This is compliant because the Appendix A block is opt-in.

2. No 403.02_api_client_token_mismatch scenario. That template scenario targets resources created/managed by a specific API client. QoS Profiles are provider-defined, read-only resources with no per-client ownership, so the scenario does not apply to either operation.

Also: the 403/404/422 responses are intentionally kept as local code-subsets (rather than $ref-ing the common responses) because the common versions include additional codes (INVALID_TOKEN_CONTEXT, IDENTIFIER_NOT_FOUND, MISSING_IDENTIFIER) that are not applicable to these operations — the same selective approach taken in ConsentManagement #29.

The CHANGELOG and API Readiness Checklist are intentionally not modified in this PR (the changelog is generated from the changelog-input below at release time), matching the ConsentManagement #29 precedent.

Changelog input

 release-note
Aligned the QoS Profiles API and its test definitions with CAMARA Commonalities r4.3 (0.8.0): reuse common schemas/responses via $ref into code/common/, add S-309/S-312 constraints and mandatory info.description section markers, and align the test definitions with the r4.3 sample-service-template.

Additional documentation

This section can be blank.

docs

[camara-validation]

CAMARA Validation — PASS (with warnings)

0 errors, 34 warnings, 6 hints | Profile: standard

View full results

[RandyLevensalor]

@hdamker @eric-murray @jlurien can you please review. IMHO, the largest potential issue is that these limits are broader than they need to be. My concern is that we will have more issues if they are overly constrained. But I'm happy to make these more reasonable.

[hdamker]

@RandyLevensalor I found only one "should" fix:

qos_profiles_retrieveQoSProfiles_400.03_empty_request_body asserts {} → 400 INVALID_ARGUMENT, but QosProfileDeviceRequest has no required properties (and no minProperties), and scenario 05_not_return_restricted_profiles returns 200 when no device/name/status is provided. So an empty body is a valid request that returns all profiles — the template's 400.03 (whose note reads "…while at least one property is required by the schema") doesn't apply to this operation. This is the same optional-filter reasoning used to drop 403.02 and MISSING_IDENTIFIER. Suggest removing this scenario and renumbering the remaining 400.xx.

The limits I would keep broad as you have chosen. All the new maxLength/maxItems/maximum constraints are on response-side schemas (QosProfile and its nested Duration/Availability, plus the 200 array), so generous bounds are non-breaking — they only cap pathological payloads, and tightening them risks rejecting valid provider implementations for little gain.

A minor point:

• The QosProfile.description pattern excludes all control characters, which also rules out newlines/tabs — fine for single-line descriptions but would exclude multiline descriptions.

[RandyLevensalor]

@hdamker

A minor point:

• The QosProfile.description pattern excludes all control characters, which also rules out newlines/tabs — fine for single-line descriptions but would exclude multiline descriptions.

Would it be worth adding a canonical CAMARA "printable text" pattern to in Commonalities?

I've updated this to allow tab, LF and CF plus added more exclusions.

[hdamker]

@RandyLevensalor sorry for the false-positive error by Validation ... already working on it: camaraproject/tooling#394. Will come with patch release of tooling soon.

[RandyLevensalor]

Note on the failing validation / Validate (P-025) check

The single blocking finding is a false positive in the validation tooling:

[P-025] Scenario-step URL version segment '/{name}' does not match expected '/vwip'
  code/Test_definitions/qos-profiles-getQosProfile.feature:16

The resource path /qos-profiles/vwip/qos-profiles/{name} is correct (api-name qos-profiles legitimately appears twice). The current v1-rc tooling ref walks every qos-profiles/… occurrence on the line and mistakes the second one's {name} for a version segment.

This is already fixed upstream in camaraproject/tooling#395 (fix/p025-first-occurrence-per-line), but the v1-rc tag this repo's camara-validation.yml pins has not yet been advanced to include it. No change is needed in this PR — the P-025 error will resolve once v1-rc is re-pointed to include that fix.

[hdamker]

No change is needed in this PR — the P-025 error will resolve once v1-rc is re-pointed to include that fix.

Done and Validation re-run shows now 0 errors, 37 warnings, 6 hints (no warnings about qos-profiles API and test definition, the warning regarding qos-provisioning will be addressed by #580

[hdamker]

Some smaller findings worth to be fixed below

[hdamker]

LGTM - thanks Randy!

Note: I reintroduced the blank lines after CAMARA:MANDATORY BEGIN markers. The GitHub suggestions had introduced within the lines four spaces each which triggered the YAML linting. Now clean and in line with camaraproject/Commonalities#651 and with the upcoming templates of Commonalities r4.4.

[hdamker]

@eric-murray would be great if you can review the changes since your approval and re-approve. Then I can create tomorrow the snapshot at the deadline.